hsdk
hsdk stands for HATEOAS Software Development Kit. This library reads from a specified 'application metadata' endpoint and generates an HTTP HATEOAS API client.
Example at play: https://esnextb.in/?gist=1ddc4e3e62196c8b9542b87a6141dff4
using
First you need to define your core sdk and in this example we'll our jsonapi.org specification-compliant endpoint:
const sdk =
The sdk
constant above is a Promise
based on a request/response to/from the home resource.
Now we can start making requests to our api, discovered 🌟magically🌟:
sdk
That will log
a list of accounts.
sdk
This will log
a single account, with the id
of 1
sdk
In POST
, PATCH
, or PUT
requests (mutations) hsdk
expects a payload
value that it uses in the body. This update
request will update the age of accounts/1
to 29
.
hsdk doesn't care what kind of API you have, only that it is discoverable via jsonapi-home
.
jsonapi-home
Much like json-home, a fantastic spec by @mnot, jsonapi-home is an attempt to allow clients to build themselves.
Using the example above, we need a HTTP server running at http://hsdkjs.getsandbox.com
that responds to GET /v1/resources
requests.
Here is a sample CURL-based request (an example of what hsdk does under the hood):
curl -X "GET" "http://hsdkjs.getsandbox.com/v1/resources" \-H "Accept: application/vnd.api+json"
Each resource MUST have the following properties:
- intent: The human name for this result, example:
list
,show
,create
,destroy
,update
- namespace: The groupings this resource is under, can be anything
- version: The version of the endpoint, if no version you SHOULD use
latest
- description: A short description for the resource
- method: The HTTP verb used
- href: A RFC 6570 URL template that the client can use directly
- mediatype: The preferred mediatype for this endpoint
That response will look like this:
HTTP/1.1 200 OKAccept: application/vnd.api+jsonContent-Type: application/vnd.api+jsonDate: Mon, 28 Nov 2016 19:50:32 GMT{"links": {"self": "https://hsdkjs.getsandbox.com/v1/resources","next": "https://hsdkjs.getsandbox.com/v1/resources?page[offset]=2","last": "https://hsdkjs.getsandbox.com/v1/resources?page[offset]=10"},"data": [{"id": "accounts-v1-list","type": "resources","attributes": {"intent": "list","namespace": "accounts","version": "v1","description": "List accounts.","method": "GET","href": "https://hsdkjs.getsandbox.com/v1/accounts","mediatype": "application/vnd.api+json"},"links": {"self": "https://hsdkjs.getsandbox.com/v1/resources/accounts-v1-list"}},{"id": "accounts-v1-show","type": "resources","attributes": {"intent": "show","namespace": "accounts","version": "v1","description": "Show an individual account.","method": "GET","href": "https://hsdkjs.getsandbox.com/v1/accounts/{id}","allowed": [["fields"]],"mediatype": "application/vnd.api+json"},"links": {"self": "https://hsdkjs.getsandbox.com/v1/resources/accounts-v1-show"}},{"id": "accounts-v1-update","type": "resources","attributes": {"intent": "update","namespace": "accounts","version": "v1","description": "Update an individual account.","method": "PATCH","href": "https://hsdkjs.getsandbox.com/v1/accounts/{id}","mediatype": "application/vnd.api+json"},"links": {"self": "https://hsdkjs.getsandbox.com/v1/resources/accounts-v1-update"}}]}