Nostalgic Primordial Monster
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    hsdkpublic

    hsdk

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

    Version Tests Stability Dependencies

    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"
     
    const sdk = hsdk({
      url: "https://hsdkjs.getsandbox.com/v1/resources",
      headers: {
        Accept: "application/vnd.api+json",
      },
    })

    sdk 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
    • allowed: A list of paths that tells the client what query or body properties are permissible.

    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",
            "allowed": [
              ["fields"],
              ["sort"]
            ],
            "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}",
            "allowed": [
              ["data", "attributes", "age"],
              ["data", "attributes", "name"]
            ],
            "mediatype": "application/vnd.api+json"
          },
          "links": {
            "self": "https://hsdkjs.getsandbox.com/v1/resources/accounts-v1-update"
          }
        }
      ]
    }

    install

    npm i hsdk

    Downloadsweekly downloads

    28

    version

    10.0.0

    license

    ISC

    repository

    githubgithub

    last publish

    collaborators

    • avatar