Implement JSON RESTful API

[soylent-grin]

We have next components in our app: Browser(client code), Proxy(backend code), TripleStore(Fuseki, SPARQL Endpoint). Here is described communication API protocol between Browser and Proxy. On any request, if user is not authorized with OAuth - return 401 Unauthorized HTTP code.

1. GET /api/v1/current_user - returns exactly the same, that GitHub returns https://api.github.com/user, but only login, id and avatar_url will be used on the client.
2. POST /api/v1/class. Creates new class. Body is JSON-LD, representing new class. If user is authorized, append user_id to class JSON-LD and transfer it to TripleStore.
3. PUT /api/v1/class/${CLASS_URI}. Modify existing class. Body is JSON-LD, representing class. CLASS_URI is URLencoded class URI. Note, that user_id parameter would not be sent - you should get it by yourself, and, if user_id is not matched current user ID - return 403 Forbidden HTTP code. If no class found by this URI - return 404 Not Found HTTP code.
4. DELETE /api/v1/class/${CLASS_URI}. Delete existing class. Body is empty. Do the same checks, as on PUT request.

[garayzuev]

How should class_uri to be created in POST query at /api/v1/class?

[soylent-grin]

Typical solution in any JSON-LD document is to store URI in @id field, for example:

{
  "@id": "http://example.org/cars/for-sale#tesla"
}

[soylent-grin]

Also, during the creation of new class via POST, you should check whether there is an existing entity with the same URI, and if it is - return 400 Bad Request HTTP Code

[garayzuev]

RESTful offers: GET /api/login - redirected to GitHub authorization page. After authorization redirected to semdesc.semiot.ru. GET /api/login/user - return json data about user from GitHub. If user are not authorized in our service returns 403 Forbidden. If token from GitHub expired then returns 401 Unauthorized. GET /api/logout - removes user cookie and removes data about user from database. If cookie are not contained in database then returns 404 Not Found. POST /api - creates new class. Body is JSON-LD, representing new class. If user is authorized, append user_id to class JSON-LD and transfer it to TripleStore, else returns 401 Unauthorized. If JSON-LD has wrong or already exists, returns 400 Bad Request. DELETE /api/${class_uri} - removes existing class with uri ${class_uri}. Body is empty. If user isn't authorized returns 401 Unauthorized. If ${class_uri} is empty returns 400 Bad Request. If class with such uri doesn't exist returns 404 Not Found. If user, who want to remove this class, didn't create it, returns 403 Forbidden. PUT /api/${class_uri} - modify existing class. Body is JSON-LD, representing class. Code are same as DELETE and POST queries.

[soylent-grin]

@garayzuev, Why did you strip class from POST, PUT and DELETE methods' URL? Now it's unclear, what are this methods supposed to do; for example, /api/login is an API request, too. Why did you use class_uri query parameter instead of clear REST-style /api/${class_uri}? Every HTTP server allows to implement basic wildcard routing.

[garayzuev]

@soylent-grin , class_uri is already query parameter.

[garayzuev]

Altered: DELETE /api/${class_uri} and PUT /api/${class_uri}

[soylent-grin]

DELETE /api/${class_uri} and PUT /api/${class_uri}

yes, that's the point. So what about class prefix in URL(/api/class/...)? Imagine, that in future we would extend our API to handle not only classes - prefixes like class make it much easier on the routing level.