api.md

API

TeSS has 2 JSON APIs, a newer JSON-API conformant API that is currently read-only, and a legacy API that supports both read and write, but only for Events and Materials.

Authentication

Both APIs use token authentication. You can see/change your API token from your TeSS profile page.

You can pass your credentials either using HTTP headers:

X-User-Email [email protected]
X-User-Token 65gONMyVZXXkgnksghzB  

or in your request:

{
  "user_email" : "[email protected]",
  "user_token" : "65gONMyVZXXkgnksghzB",  
  "material": {
    "title": "API example",
    ...
  }
}

JSON-API

A read-only API conforming to the JSON-API specification. Currently supports viewing, browsing, searching and filtering across Events, Materials, Workflows, Providers and Users.

Click here to view documentation

A record can be viewed through this API by appending .json_api to the URL, for example:

http://localhost:3000/materials.json_api
http://localhost:3000/materials/1.json_api

Legacy API

A simple read/write API supporting Events and Materials.

Click here to view documentation

A record can be viewed as json by appending .json to the URL, for example:

http://localhost:3000/materials.json
http://localhost:3000/materials/1.json

Example

To create a material by posting, post to this URL:

http://localhost:3000/materials.json

Structure the JSON thus:

{
    "user_email": "[email protected]",
    "user_token": "your_authentication_token",
    "material": {
        "title": "API example",
        "url": "http://example.com",
        "description": "This API is fun and easy",
        "doi": "Put some stuff in here"
    }
}