CTERA Portal RESTful API Basics
In this section
CTERA Object Model
In accordance with the convention of RESTful Web services, the CTERA API exposes a uniform namespace, or schema, containing objects, each of which is represented by a unique URI (Uniform Resource Identifier).
An object consists of attributes. Each attribute has an ID and a value, and may be another object, a collection of objects, or a basic scalar value (such as an integer, string, or date).
Each object belongs to a class. Classes define an object type, including a list of attributes and their types, as well as a list of extended methods supported by the objects in the class.
The definition of all the classes supported by the CTERA Portal is collectively named the CTERA Portal schema.
Supported HTTP Methods
The following HTTP methods are supported by CTERA API objects.
|
HTTP Method
|
Description
|
|---|---|
|
GET
|
Retrieves an object
|
|
PUT
|
Replaces (updates) an object or an entire collection
|
|
POST
|
Invokes an extended method on an object
|
|
DELETE
|
Deletes an object
|
Examples
The following are examples of potential uses of the CTERA API:
The list of ALL the users in the system can be retrieved from the URI /admin/api/users.The details of the user with the username jsmith can be retrieved or modified using the URI /admin/api/users/jsmith.The lastName attribute of the user jsmith can be retrieved, with the HTTP GET method, or modified, with the HTTP PUT method, using the URI /admin/api/users/jsmith/lastName.The API Base URL
The CTERA Portal API is accessed via its base URL, which is: http://virtualPortal/admin/api
Where virtualPortal is the name of the virtual portal.
For example, the API base URL for a virtual portal named "portal.company.com" is:
http://portal.company.com/admin/api
It is recommended to access the CTERA Portal API securely, using HTTPS. For example:
https://portal.company.com/admin/api
Note: Throughout this documentation, the base URL is referred to as {BASE_URL}. In Java code examples, the URL is referred to as baseURL.
User Authentication
In order to gain access to the CTERA Portal API functions, the client must authenticate with an administrator username and password. For more information, see Logging In and Out.
HTTP Response Status Codes
The REST methods in the CTERA API all return one of the following HTTP status codes:
|
In this field...
|
Do this...
|
|---|---|
|
200 OK
|
The call completed successfully.
Any result is included in the HTTP response body.
|
|
400 Bad Request
|
The request is incorrectly formatted.
The error text is included in the HTTP response body.
|
|
401 Unauthorized
|
The client is required to log in, as described in Logging In.
The client must support HTTP cookies.
|
|
403 Forbidden
|
The client does not have sufficient credentials to perform the requested operation.
For login requests, the provided username or password is invalid.
|
|
404 Not Found
|
The requested object was not found.
|
|
500 Internal Server Error
|
An error occurred while handling this request.
The detailed error description is included in the HTTP response body.
|