json_hyperschema_client_builder v0.12.0 JSONHyperschema.ClientBuilder

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

Link to this section Summary

Functions

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).

Link to this section Functions

Link to this macro

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

(macro)

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.

Link to this macro

defapi(api_module, app, json)

(macro)

Defines an API client based on a JSON hyperschema.

This macro defines submodules for each defined type (via defresource).

Example

defmodule Foo.Client do
  schema_json = File.read!(schema_path)
  defapi __MODULE__, :my_app, schema_json
end

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 the following:

...
"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.

Link to this macro

defresource(api_module, name, resolved_hyperschema)

(macro)

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).