rest.md

REST-HAL endpoints

Summary

Motivation

The requirement of expose the domain via HTTP to other applications.

Services

List

• Verb: GET
• Template: http://rest.oss.tyba.cc/<resource>?<query>
• Return: 200 - A list of HAL resources

Var	Description
<resource>	name of the resource, exactly the same name of the struct
<query>	a serie of URL params using as key the name of the methods of <Entity>Query struct, the following types are supported(int, float, string and mgo.ObjectId)
limit	number of resources to return
skip	number of resoueces to skip from the begining of the result
order	sorting of the result, using the format from mgo (eg.: -_id,created)

Any call to LIST can be channing with other using the header X-Subrequest, following the next schema:

X-Subrequest: <uri>,<alias>

The <uri> is the URI to any other list request from same or other resource, the format of the URI is exactly the same of any List request. The <alias> allows to make refereces to this subrequest in the subsequents requests.

Placeholders can be used as values on the <query> values following the pattern <request-alias>.<flield-name>, the request-alias for the root request is root.

The result of the subrequest are returned as embedded resource using as name the alias of the request.

Example:

GET /proposal?limit=10
X-Subrequest: /person?findById=<root.person_id>,foo
X-Subrequest: /repository?findById=<foo.repositories_id>&findByStatus=published&limit=3  

Get

• Verb: GET
• Template: http://rest.oss.tyba.cc/<resource>/<id>
• Return: 200 - A HAL resource

Var	Description
resource	name of the resource, exactly the same name of the struct
id	string representation of a mgo.ObjectId

Create

• Verb: POST
• Template: http://rest.oss.tyba.cc/<resource>
• Body: A HAL resource
• Result: 201

Var	Description
resource	name of the resource, exactly the same name of the struct

Update

• Verb: PATCH
• Template: http://rest.oss.tyba.cc/<resource>/<id>
• Body: A partial HAL resource
• Result: 201

Var	Description
resource	name of the resource, exactly the same name of the struct
id	string representation of a mgo.ObjectId

A partial HAL resource with the fields and values needed to be updated.

Custom Services

• Verb: GET
• Template: http://rest.oss.tyba.cc/custom/<service>?<query>
• Result: 200 - A HAL resource

In some cases we will need custom services, this services can merge several entities or make virtual ones, or even random properties, the goal is fit the corner cases where the common services are not enough.

Var	Description
service	name of the service
query	free query params as needed by the service

Responses

All the responses will follow the HAL standard, this standard is proposed over JSON-LD due to my exprience with it and the lack of high level support of JSON-LD in Go.

The library nvellon/hal will be used in the response generation, is very easy of use and understand.

Drawbacks

Why should we not do this?

Alternatives

What other designs have been considered? What is the impact of not doing this?

Unresolved questions

What parts of the design are still TBD?