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.

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:

import hsdk from "hsdk"
import axois from "axois"

const sdk = hsdk({
  home: {
    url: "https://hsdkjs.getsandbox.com/v1/resources",
    headers: {
      Accept: "application/vnd.api+json",
    },
  },
  // You tell us how to make the request
  http: ({url, method, payload}) => axois({
    method,
    url,
    data: payload,
    responseType: "JSON",
  }),
  // You tell us how to get to the JSON:API data
  receive: (body) => body.data,
})

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
  .then((client) => client.accounts.v1.list())
  .then((response) => console.log({message: "List", payload: response.data}))

That will log a list of accounts.

sdk
  .then((client) => client.accounts.v1.show({id: "1"}))
  .then((response) => console.log({message: "Show", payload: response.data}))

This will log a single account, with the id of 1

sdk
  .then((client) => {
    return client.accounts.v1.update({
      id: "1",
      payload: {
        data: {
          id: "1",
          type: "accounts",
          attributes: {
            age: 29
          }
        }
      }
    })
  })
  .then((response) => console.log({message: "Update", payload: response.data}))

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 OK
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Date: 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"
      }
    }
  ]
}