Interact with ComodIT’s API

Operations are triggered through standard HTTP methods on a resource’s URL. A particular URL generally points to an entity or an entities collection. Given the situation, HTTP methods usually have the same effect: a POST on a collection creates a new entity, a DELETE on an entity removes it from its collection, etc.

Collections

The URL for a collection ‘A’ always has the form https://my.comodit.com/api/A where https://my.comodit.com/api is the URL of ComodIT’s API. On such URL, the following methods are usually defined:

GET: returns the entities of the collection in a list (which can be paginated, see below).
POST: adds an object to the collection.

List entities with Curl

In order to list the entities of the collection ‘A’, just issue an HTTP request with the GET method on the collection URL:

curl -X GET http://my.comodit.com/api/A --user admin

This will return a JSON representation of the collection (content type application/json):

{
    "count": 1,
    "offset": 0,
    "total": 1,
    "items": [
        {
            ...
        },
        ...
    ]
}

The ‘items’ array Such a result always has the following four fields:

count: The number of items in the provided result set.
offset: The offset in the result set (used for paging through results, an offset of 0 means that the result set starts at the first result).
total: The total number of objects in the result set.
items: An array that contains the actual result i.e. the entities' representation.

Create an entity with Curl

In order to create an entity, you must provide the representation of the new entity using the HTTP POST method. With curl, you could do this with the following command. Note that you must specify the content type of the request to be ‘application/json’.

curl -X POST -H"Content-Type: application/json" -d @entity.json http://my.comodit.com/api/A --user comodit

Where entity.json is a file containing the JSON representation of the entity. The system replies with a 200 HTTP status code and the JSON representation of the created entity.

Manipulating entities

The URL of an entity ‘a’ part of a collection ‘A’ always has the form https://my.comodit.com/api/A/a. You can find this URL in the documentation of each entity. On such URL, the following methods are usually defined:

GET: returns the representation of the entity.
PUT: updates the entity based on the provided representation.
DELETE: deletes the entity.

Read an entity with Curl

In order to get the representation of a resource, just issue an HTTP request with the GET method:

curl -X GET http://my.comodit.com/api/A/a --user comodit

This will return a JSON representation of the entity (content type application/json):

{
    ...
}

Modify an entity with Curl

In order to modify an entity, you must provide the modified representation using the HTTP PUT method. With curl, you could do this with the following command. Note that you must specify the content type of the request to be application/json.

curl -X PUT -H "Content-Type: application/json" -d @entity.json http://my.comodit.com/api/A/a --user comodit

where entity.json is a file containing the JSON representation of the entity. The system replies with a 200 HTTP status code and the representation of the updated entity.

Delete an entity with Curl

In order to delete an entity, just issue an HTTP request with the DELETE method:

curl -X DELETE http://my.comodit.com/api/organizations/A/a --user comodit

The server replies with a HTTP 200 status code.

Once deleted, trying to read the entity will result in an HTTP 404 status code and a developer friendly error message in JSON:

{
    "error": ["No host with name HAL"],
    "status": 404
}

where error field is an array of error messages and status the HTTP error code.

Sub-collections

Some collections are defined in the context of a particular entity. For example, let an entity ‘a’ be part of collection ‘A’ and have a collection ‘B’ containing an entity ‘b’. The URL to collection ‘B’ is then:

http://my.comodit.com/api/A/a/B

Therefore, entity ‘b’ is accessed using URL:

http://my.comodit.com/api/A/a/B/b

Of course, operations defined in previous sections apply in the same way.

Notations

For readability’s sake, URL may be shortened. For example URL:

http://my.comodit.com/api/A/a/B/b

becomes:

/A/a/B/b

Finally, relative URLs to generic sub-collections defined for different entity types may be defined. For example, in the context of entity ‘a’, the URL to entity ‘b’ may be written:

B/b

To summarize, following notations are equivalent (in the context of entity ‘a’):

http://my.comodit.com/api/A/a/B/b
/A/a/B/b
B/b