Using the Designer

Introduction

How to perform Common Tasks in the API Designer. Also Definitions of common terms, and some Tips about how things work.

Common Tasks [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:

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}”

Tips [top]

The API Designer does not support sparse (non-contiguous) arrays”

All tables (arrays) passed to or returned from API calls need to be contiguous (not contain any nil elements). If you want to remove an item from an array you use the table.remove() function rather than setting the element to nil, see the example code here Delete a table element.

Note: Setting an element to nil is a valid way of deleting a table element, and may be more appropriate than table.remove() for some purposes.

However it is not compatible with the HTTP methods created by the API designer.

There is no Server type checking for URI parameters

This is because URI parameters are are always passed as strings (because they are part of the HTTP URI request). Therefore there is no way for the Server to identify the datatype (of the incoming string data) and check that it matches the API specification.
Note: This was not a design decision that we made — instead it is part of the HTTP method design standards, URI parameters are always passed as text.

However all is not lost! If you need type checking on your parameters you can simply use Structured Body instead — which is passed as JSON and includes type information. Be aware that the Structured Body is not available for all HTTP methods, they are only supported for: POST, PATCH and PUT.

Leave A Comment?