Core Concepts

The API Designer uses a few simple concepts that you need to be familiar with. These concepts are based on the principles of RESTful APIs, HTTP and JSON.

Modern RESTful APIs typically transmit data structured as JSON. The API designer is a GUI tool that works with JSON — so you don’t need to create JSON manually.

The last two items on this page Design Methodology and Useful Techniques are different, as they contain material that is specifically about using the API Designer.

JSON Grammar [top]

The end result of working with the API Designer is to produce a JSON Grammar file that gives a formal description of the API you defined. This formal description of the API can be used to build a Server implementation of the API, or to create a Client that can be used to call the API.

Interactions [top]

Every API boils down to providing methods or functions that can be called by an API client to perform actions using the API. In the API Designer we call these Interactions.

An interaction will consist of information such as:

  • The Path to call for the Interaction
  • An optional Resource Identifier “/{id}” can be appended to the Path
  • What HTTP method to use — i.e. POST/GET/PUT etc
  • The parameters or JSON Resources the interaction accepts
  • What, if any data is returned by the API

Resources [top]

The Designer allows you to create re-usable data structures (user defined types) — we call these data structures Resources. Resources can be used within Interactions or nested within other Resources. Resources are a powerful tool for ensuring the consistency of an API. And as an added benefit they can actually reduce design time (particularly for large/complex APIs).

Resources are composed of the following:

  • Simple data types
  • Other Resources
  • Arrays of simple types
  • Arrays of other Resources

Responses and Errors [top]

One of the key aspects of an API is to have a well defined and consistent response structure. When an interaction succeeds, it should return the resource(s) that were requested. When an interaction fails it should return error information relating why the interaction failed so that the user can take corrective action. The API Designer responds with two key pieces of information that are contained in the form of an HTTP response: An HTTP response body, and an HTTP response code. The response body contains the resource/information requested if the interaction succeeds, or the error information if the interaction fails. The HTTP response code indicates the class of outcome resulting from the interaction (2xx – success; 4xx – client error; 5xx – server error).
Note: A table containing the (much less interesting) HTTP Response headers is also returned.

The API Designer allows you to define the the response body format as: Resource, Structured or Custom. For example a Response (response body) that contains a “Person” Resource looks like this:

The JSON envelope returned for this Response looks like this:

{
    "data": {<Person Resource>}
}

Here is an example of a successful Response:

This is the JSON envelope for an Error:

{
    "error": { Error details }
}

Here is an example showing an Error:

Data typing [top]

The API Designer only has three basic types:

  • Simple types: – DateTime, String, Numeric and Boolean.
  • Complex types: a table of name value pairs — Resources are re-usable complex types
  • Arrays: a list of zero to many items

With this is possible to describe any kind of data you can imagine with a minimum of complexity.

Other Definitions [top]

Various other terms that we use in the API Designer.

  • Member

    An element (variable, resource or array) used in parameters, structured bodies and responses.

  • URI parameters

    These are standard HTTP parameters that are included in the URI/URL

  • HTTP body types:
    • Parameters

      Standard HTTP body parameters that are included in the body of the message.

    • Structured body

      A JSON structured body composed of various member elements.

    • Custom body

      A placeholder for a user defined body that is not JSON (i.e., XML, text, HTML, etc).

  • Resource identifier

    This is a standard HTTP resource identifier. These are defined in the Path of an Interaction using “{id}” syntax, for example: “Path/{id}”, “Patient/{id}” or “Patient/address/{id}”

Design methodology [top]

There are two basic design approaches: Create Resources first and then use them in Interactions (or other Resources), or create Interactions and then factor out Resources as you become aware of them.

In reality the best way is probably to take a “hybrid” approach — define the obvious Resources (the ones you already know about) at the start — then factor out other Resources (that you were not originally aware of) as you notice them.

Using the Designer makes a hybrid approach viable as it is much easier to “factor out” Resources than if you are creating an API manually (for example, by hand-coding JSON). In turn this makes it much easier to create a high quality API with well designed data structures.

Useful Techniques [top]

These are some key techniques that are used with the API Designer:

  • Exporting a JSON Grammar file from the API Designer.

    Typically every time you make API changes you will export the JSON Grammar, and then import the updated grammar into your Server channel or Client channel. The option to export the grammar is available while you are editing an API.

    Follow these steps:

    1. Open the API you wish to export the grammar from.
    2. Click the JSON button at the top of the screen:
  • Importing a JSON Grammar file into an Iguana Server Channel.

    This technique is used to update your Server channel when changes are made to the API. First you export the changed grammar from the Designer, then you import it into the Server channel.

    Follow these steps:

    1. Export the JSON grammar (see above).
    2. Open the Server channel for your API.
    3. Hover the cursor over the arrow to the right of “grammar.json” and use Replace to load the new grammar file from disk:
  • Importing a JSON Grammar file into a Standalone Iguana Client Channel.

    This technique is used to update a Standalone Client channel when the API is updated. First you export the changed grammar from the Designer, and then import it into the Client channel.

    Follow these steps:

    1. Export the JSON grammar (see above).
    2. Open the Client channel for your API.
    3. Hover the cursor over the arrow to the right of “grammar.json” and use Replace to load the new grammar file from disk.
  • Adding code to Handler functions in an Iguana Server Channel.

    This is done in the Iguana Server channel for your API. When you build an Server Channel from an API it contains stub (empty) handler functions that correspond to each of the Interactions defined in the API. You will need to add code these functions to implement the business logic for the API.

    For more information, see: Creating handler code.

  • Importing a JSON Grammar file into the API Designer.

    This is worth knowing about, though you may not use it very often. Importing a JSON Grammar file provides a method for duplicating an existing API, simply export the grammar and then import it back into the Designer using a different name.

    Follow these steps:

    1. Go to My APIs.
    2. Click the + Import API link at the bottom of the left pane:

Leave A Comment?