Building an API Server


Once you have created all the Resources and Interactions for your API, then you can build an API Server (or build an API Client) from the grammar you defined in the Designer.

There are two components required to build an API Server: A JSON grammar file, and our Server API Framework. The framework interprets the grammar file and builds corresponding stubcode. Each Interaction that you created in the API Designer will have a corresponding stub (empty) function in the generated code. You will need to populate each stub function with the necessary code to implement the business logic for your API.

Creating an API Server is easy — you just use the Generate option in the Designer and it automatically creates the all the Lua code for the server (including the framework and the JSON grammar file).

There are two ways to create an API Server channel:

  • Generate a project zip file and import it into a From HTTPS channel
  • Generate the API Server channel directly into an Iguana instance that is accessible over the internet

For subsequent updates you can import the JSON grammar file from the API designer into your translator project without regenerating the entire API framework — this is the most convenient workflow for incremental API development.

Generate the API Server code [top]

First we need to generate the Server code that we will use in our server channel.

  1. Open your API and click on the Generate link.
  2. Generate a Server project zip file — Click the API Server Zip link:

Tip: If you are using a web enabled Iguana Translator to develop your interface then you can use the Direct option to export the API directly from the Designer into your Iguana instance.

Load the Server Code [top]

Next we need to import that code into an Iguana Translator channel that we will use for the server.

Note: This step is not required if you chose the Direct option in the Tip above.

  1. Create a channel for the Server, with these properties:
    • Source: From HTTPS
    • Destination: To Channel
    • Channel Name: “<Your Server Name>” (omit the angle brackets “<>”)
    • URL Path: “<your-server-name>/”
  2. Import the server project zip file into the From HTTPS source of your channel.

Creating handler code [top]

Now we need to add code to the stub “handler functions” that were generated for the API — there is a handler function generated for each interaction defined in the API. We will demonstrate this by adding some trivial handler code that causes a GET function to return a string value of “Hello”.

In a live/production system this code would be much more complex, including things like: Business logic, error checking, database calls, calling 3rd party APIs etc etc.

  1. Edit the From HTTPS source code the API Server.
  2. View the code for the handler function, for example the person.get method:
  3. Add the handler code, for example the following at line 9: = "Hello"
  4. The code now looks like this:
  5. Save a commit.
  6. And this is what it looks like when you call the handler from a generated Client:

Leave A Comment?