Overview¶

Below are the documents that describes the resources that make up the official SisComando API.

1. Current Version
2. Schema
3. Resources
4. HTTP Verbs
5. Authentication
6. HATEOAS
7. Pagination
8. Requests
9. Cross Origin Resource Sharing (CORS)

Current Version¶

By default, all request must be sent with v2 prefix:

http://api.siscomando/api/v2

Schema¶

All API access is over HTTPS, and accessed from the api.siscomando. The current schema is https://api.siscomando/api/<v2>/<resource>/[<resource_id>] where:

• <v2> is version.
• <resource> are the documents as /users, /issues, /comments, etc.
• [<resource_id>] optional request for specific item.

Resources¶

The SisComando is a miner. It can to integrate any kind, from any source, at massive scale. Currently, the main resources available are:

• Users
• Issues
• Comments

HTTP Verbs¶

Where possible, API v2 strives to use appropriate HTTP verbs for each action. The following table shows the implementation of CRUD operations via REST where Collection to this purpose can be considered Table (relational) and Documents as a tuple (or row):

Authentication¶

Customizable Basic Authentication (RFC-2617) is supported. All REST API endpoints are secured, which means that a client will need to provide the correct credentials in order to consume the API.

$ curl -i https://api.sicomando
HTTP/1.1 401 UNAUTHORIZED
Please provide proper credentials.

$ curl -u "user@example.com:password" -i https://api.sicomando
HTTP/1.1 200 OK

HATEOAS¶

All resources have _links properties linking to other resources. This is provided by support the Hypermedia as the Engine of Application State (HATEOAS). So each GET responses includes a _links section. Links provide details on their relation relative to the resource being accessed, and a title. These are meant to provide explicit URLs so that proper API clients don’t need to construct URLs on their own.

Pagination¶

Requests that return multiple items will be paginated to 25 items by default. You can specify further pages with the ?page=<integer>. You can also set a custom page size with max_results.

$ curl -i http://api.siscomando/api/v2/users?max_results=20&page=2
HTTP/1.1 200 OK

 $ curl -u "s@super.com:123" http://api.siscomando/api/v2/users
 "_links":{
      "self":{
            "href": "users?max_results=10",
            "title": "users"
      },
      "last":{
            "href": "users?max_results=10&page=6",
            "title": "last page"
      },
      "parent":{
            "href": "/",
            "title": "home"
      },
      "next":{
            "href": "users?max_results=10&page=2",
            "title": "next page"
      }
  } # content omitted...
}

$ curl -u "s@super.com:123" http://api.siscomando/api/v2/users
... # omitted for explanation ...
"_meta":{
     "max_results": 25,
     "total": 58,
     "page": 1
 }

Requests¶

Nada pode ser

Cross Origin Resource Sharing (CORS)¶

CORS allows web pages to work REST APIs, something that is usually restricted by most browsers ‘same domain’ security policy. The SisComando REST API supports CORS for AJAX requests from any origin.

Here’s a sample request sent from a browser hitting http://example.com:

$ curl -u 's@super.com:123' -i http://api.siscomando/api/v2/users \
-H "Origin: http://example.com"
HTTP/1.0 200 OK
Access-Control-Allow-Origin: http://example.com
Vary: Origin
Access-Control-Allow-Headers:
Access-Control-Expose-Headers:
Access-Control-Allow-Methods: OPTIONS, HEAD, DELETE, POST, GET