The Graviton API

Most services on a graviton instance have a predictable API surface.

Each service comes in two parts, the schema declaration as well as the actual API endpoints.

The examples below are based around the /core/app/ services which usually exist on all graviton instances.

Only a very small amount of graviton services do not follow this convention. In fact the only currently exception should be the version service which has its own documentation.

More documentation is always available

Full documentation on all the available services is self hosted on each graviton instance.

A basic service listing may be found at the root URL.

curl https://example.com

A more complete overview is available through a swagger definition.

curl https://example.com/swagger.json

Endpoints

Schemas

All of our output has adequate schema documentation that may be used for validation of graviton data structures. Much more important is that this schema information allows us to add inline documentation on the semantics of the data provided by graviton.

Schema describing an individual document

curl https://example.org/schema/core/app/item

Schema describing a collection of documents

curl https://example.org/schema/core/app/collection

Collection schemas are available as a convenience so you may use them against our collection endpoints. For the most part they contain the same data you would also find in the corresponding item schema.

APIs

GET collection of documents

curl https://example.org/core/app/

You can search in collections using RQL.

Getting invalid data with RQL select() operator

Note that it is possible to export data that does not adhere to the schemas using the RQL select() operator.

As a rule of thumb, if you plan on modifying retrieved documents and want to PUT them into graviton again, you should probably not use the operator.

POST a new document (server defines id)

curl -X POST -d '{}' https://example.org/core/app/

Check the response headers to see what id your document was stored at.

PUT a new document or update an existing one (client defines id)

curl -X PUT -d '{"id": "my-id"}' https://example.org/core/app/my-id

This is also referred to as an upsert operation.

GET an existing document

curl -X GET https://example.org/core/app/my-id

DELETE a document

curl -X DELETE https://example.org/core/app/my-id