Implementation Scenarios

Introduction

Once you have documented your API, then you are ready to build the API Server and/or Client from the grammar you defined in the Designer.

Scenario 1: Client and Server [top]

This is the first usage scenario for the API Designer. This is when you design a new API, and then use Iguana to implement both the API Server and Client.

If you are starting from scratch then you can save a lot of time by using the API Designer to design your API. Once the API is designed you can generate both the Server and Client for use in Iguana. You will also need to add custom Lua code to the Server and the Client — but this is much less effort than hand-coding the API, Server and Client.

Follow these steps to implement this scenario:

  1. Build the API Server.
  2. Build the API Client.
  3. Replace the JSON grammar in the Server channel to apply API updates.

    For subsequent API changes you will need to generate a new JSON grammar file from the Designer and import it into your Server channel.

Scenario 2: Standalone Server [top]

This is the second usage scenario for the API Designer. This when you design a new API, then you use Iguana to implement the API Server, and finally you call that API from a third party tool using REST calls.

This is similar to the first option, you still need to create your API from scratch, but then you want to call it from a third party tool (not Iguana). You still use the Designer to create and generate the Server. But then you use another tool to make standard REST calls to communicate with the server (which runs as a channel on an Iguana instance). You will also need to add custom Lua code to the Server — but this is considerably less effort than hand-coding the API and the Server.

Follow these steps to implement this scenario:

  1. Build the API Server.
  2. Call the API using standard REST calls.

    Because the API uses standard REST Methods the API this means you can use the API from any programming environment that supports REST. For example: You could use our standard builtin net (HTTP) functions to make RESTful calls to an API server.

  3. Replace the JSON grammar in the Server channel to apply API updates.

    For subsequent API changes you will need to generate a new JSON grammar file from the Designer and import it into your Server channel.

Scenario 3: Standalone Client [top]

This is the third usage scenario for the API Designer. This is when you document an existing third party API in the Designer, then you use Iguana to implement the API Client, and finally you use that client to communicate with the existing third party RESTful API.

In this case you already have a RESTful API server and you want to create a Lua Client for the Iguana Translator. You will need to document the existing API in the Designer and then generate a Client to communicate with the existing API. You will also need to add custom Lua code to the Client — but this will be considerably less work than hand-coding the Client.

Please contact us for more information about this scenario as the exact details will differ depending on the API you are connecting to.

Follow these steps to implement this scenario:

  1. Build the API Client.
  2. Add the JSON grammar file to the Client channel project,  either in local files, or the /other directory:

    Because we are using a third party APIs the JSON grammar file must be included as part of the project for the Client channel.

  3. Add the grammar argument to the call instantiating the Client — to specify the grammar.json file added above:
  4. Add the headers argument to the call instantiating the Client — to specify any custom headers required:
  5. Add authentication information for your server — update  the #SERVER_URL# and #ACCESS_TOKEN# placeholders in the main() module:
  6. Replace the JSON grammar in the Client channel to apply API updates.

    For subsequent API changes you will need to generate a new JSON grammar file from the Designer and import it into your Client channel.

  7. Depending on the specifics of your API there may be other customization required — please contact us if you have any questions.

Please don't hesitate to take anonymous feedback survey or leave us a comment.

Leave A Comment?