json_hyperschema_client_builder v0.6.0 JSONHyperschema.ClientBuilder

This module provides a series of macros that transform a JSON hyperschema into set of client modules.

Summary

Macros

Builds a function based on the needs of the schema

Defines an API client based on a JSON hyperschema

Defines a module for a type (found in a JSON hyperschema definition) and defines a function for each of the type’s links (via defaction)

Macros

defaction(api_module, method, name, path, params, body_schema)

Builds a function based on the needs of the schema.

  • JSON pointers inside hrefs become function parameters. For example: "href": "/things/{(%23%2Fdefinitions%2Fthing%2Fdefinitions%2Fidentity)}" contains the JSON pointer #/definitions/thing/definitions/identity which is resolved to the ‘thing’ attribute ‘id’, so the function becomes: Foo.Bar.get(id, ...)

  • if the action has a schema, the last function parameter is params. And when the function is called the params are checked against the action’s schema.

  • if its the type of method that has a body, the params are JSON encoded and sent as the body, otherwise they are added as URL query parameters.
defapi(api_module_name, json)

Defines an API client based on a JSON hyperschema.

This macro defines the top-level client module and submodules each defined type (via defresource).

Example

schema_json = File.read!(schema_path)
defapi Foo.Client, schema_path

will create a submodule under Foo.Client for each type definition in the schema, and a function for each API call described by “links”.

If the schema contains

...
"definitions": {
  "bar": {
    "links": [
      {
        "title": "Info",
        "rel": "self",
        "description": "Information about a bar",
        "href": "/bars/{(%23%2Fdefinitions%2Fbar%2Fdefinitions%2Fidentity)}",
        "method": "GET",
        ...
      }
    ]
  }
}
...

The function get/1 in the module Foo.Client.Bar will be defined. The function’s parameter will be the value of the identity to be inserted in the URL.

defresource(api_module, name, resolved_hyperschema)

Defines a module for a type (found in a JSON hyperschema definition) and defines a function for each of the type’s links (via defaction).