hsdk

hsdk

hsdk stands for HATEOAS Software Development Kit. This library reads from a specified 'application metadata' endpoint and generates an HTTP HATEOAS API client.

using

import hsdk from "hsdk"

hsdk({protocol: "http", host: "hsdkjs.getsandbox.com", root: "v1/resources"})
  .then((client) => client("v1Accounts").list())
  .then((value) => console.log(value))

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 on hsdkjs.getsandbox.com that responds to http requests to GET /v1/resources.

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
• 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
• allowed (FUTURE): An allowed list of fields
• query (FUTURE): An allowed list of query parameter names

That response will look like this:

HTTP/1.1 200 OK
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Date: Mon, 28 Nov 2016 19:50:32 GMT

{
  "links": {
    "self": "http://hsdkjs.getsandbox.com/v1/resources",
    "next": "http://hsdkjs.getsandbox.com/v1/resources?page[offset]=2",
    "last": "http://hsdkjs.getsandbox.com/v1/resources?page[offset]=10"
  },
  "data": [
    {
      "id": "v1-accounts-list",
      "type": "resources",
      "attributes": {
        "intent": "list",
        "namespace": "v1/accounts",
        "description": "List accounts.",
        "method": "GET",
        "href": "http://hsdkjs.getsandbox.com/v2/accounts",
        "query": {
          "filter": true,
          "sort": true
        },
        "mediatype": "application/vnd.api+json"
      },
      "links": {
        "self": "http://hsdkjs.getsandbox.com/v1/resources/v1-accounts-list"
      }
    },
    {
      "id": "v1-accounts-show",
      "type": "resources",
      "attributes": {
        "intent": "show",
        "namespace": "v1/accounts",
        "description": "Show an individual account.",
        "method": "GET",
        "href": "http://hsdkjs.getsandbox.com/v1/accounts/{id}",
        "query": {
          "fields": true
        },
        "mediatype": "application/vnd.api+json"
      },
      "links": {
        "self": "http://hsdkjs.getsandbox.com/v1/resources/v1-accounts-show"
      }
    },
    {
      "id": "v1-accounts-update",
      "type": "resources",
      "attributes": {
        "intent": "update",
        "namespace": "v1/accounts",
        "description": "Update an individual account.",
        "method": "PATCH",
        "href": "http://hsdkjs.getsandbox.com/v1/accounts/{id}",
        "allowed": [
          [
            "data",
            "attributes",
            "age"
          ]
        ],
        "mediatype": "application/vnd.api+json"
      },
      "links": {
        "self": "http://hsdkjs.getsandbox.com/v1/resources/v1-accounts-update"
      }
    }
  ]
}