Review a complex API Server and Client

Introduction

This page presents a more comprehensive “second cut” of a Patient Demographics API for you to review. This version is intended to give an impression of how it is to work with a more realistic API design — this version demonstrates most features of the API Designer.

The API is composed two parts: The API design in the Designer and the code for the API in the Iguana Translator. We suggest that you inspect the API design first and then look at the corresponding code.

We also encourage you to experiment with changing the design and the code. Don’t worry about breaking things — you can always re-import the originals from this page.

For a simpler example look at the very basic “first cut” of the Patient Demographics API in Review a basic API Server and Client.

You can log into the API designer here: https://designer.interfaceware.com/ (click on create a new account if you don’t have an account yet).

Import the API [top]

Th quickest way to create the API Design and the Client and Server code is simply to import the completed examples.

  1. Import the JSON Grammar into Designer:
  2. Create a channel for the Server, with these properties:
    • Source: From HTTPS
    • Destination: To Channel
    • Channel Name: “Patient Demographics server V2”
    • URL Path: “patient-demographics-server-v2/”
  3. Import the API Server code into the new Server channel:
  4. Create a channel for the Client, with these properties:
    • Source: From HTTPS
    • Destination: To Channel
    • Channel Name: “Patient Demographics client V2”
    • URL Path: “patient-demographics-client-v2/”
  5. Import the API Client code into the new Client Iguana:

Review the API Design [top]

This is the structure of the “second cut” of our API, as you can see it is is a lot more complex than the “first cut” (and is somewhat more realistic).

  1. Log into the API designer.
  2. Go to My APIs.
  3. Open the Patient V2 API.
  4. View the Resources.
  5. There are six Resources, for example the Patient looks like this:
    Note: We expanded the Dependencies to show where the resource is used.
  6. Try editing  Resources, don’t worry about breaking things — you can always import the grammar again.
  7. View the Interactions.
  8. There there are six Interactions grouped under Patient, for example the Create look like this:
  9. Try editing the Interactions, don’t worry about breaking things — you can always import the grammar again.
  10. For bonus points you can open the JSON Grammar file and see if you can spot the Resources and Interactions:

Create the SQLite Database [top]

  1. Create an Iguana channel to create the SQLite database, using these settings:
    • Channel name: “Create SQLite DB” (you can use any name)
    • Source: From Translator
    • Destination: To Channel
  2. Import the code to create the database:
  3. Check that the DB tables have been created:
    • If the SELECT statements run without errors it then the tables have been created:
    • Tip: You can also confirm that the table structures are correct — this could be useful if you update the script to change the table structures and need to confirm that the changes are applied correctly.

      • Compare the table CREATE statement stored in SQLite to the one used in the script
      • Inspect the sql field the sqlite_master system table to view the CREATE statement:
        If a table was not created you will see an error like this:
  4. Comment out two lines 19 and 22 — to ensure you don’t unexpectedly recreate data (which can be very confusing during testing).
    • Line 19 –sqlite.DropTables(conn) to prevent accidentally deleting tables
    • Line 22 –sqlite.CreateTables(conn) to prevent accidentally recreating data
  5. Set the DoInsert flag on line 39 to false to prevent deleting and recreating data (which can be very confusing during testing).
  6. Use the Create SQLite DB channel for re-creating data while testing the code:
    • Uncomment line 19 Set the DoInsert flag on line 39 to false — to drop the tables
    • Uncomment line 22 then comment it out again — to create the tables
    • Set the DoInsert flag on line 39 to true then back to false — to re-create the data

Review the API Server Code [top]

  1. Look at the code for the Server channel Patient Demographics server V2.
  2. Open some of the handler functions, and review the handler code (all handler functions include code).
  3. Feel free to modify the the handler code if you wish, you can always rollback to the initial commit.
  4. If you are interested you can also look at the code in the various other modules, but it is not necessary as the only code you ever need to change is the handler functions above.
  5. If you like a challenge can try adding handlers for Diagnoses and Procedures
    1. First you need to add resources and interactions in the API Designer.
    2. You will need to update the DB tables to handle to match (probably new Diagnosis and Procedure tables)
    3. Then you need to import the updated JSON Grammar into the server channel.
    4. Next you will add the code for the new handler function.
    5. Finally you will need to add some test code for the new handlers to the client channel.

Review the API Client Code [top]

  1. Look at the code for the Client channel Patient Demographics client V2.
  2. Open the main module and look at the main() function.
  3. Starting at line 44 there are API Server calls corresponding to all the API functions.
  4. Test out functions by uncommenting the corresponding R:submit{…} line.
    Note: The easiest way to test is to run (uncomment) a single function at a time.
  5. Repeat Create the SQLite Database > step 6 to recreate the data when the code does not work (you will end up doing this a lot).
  6. The test queries in the Create SQLite DB channel are useful for checking the effects of various functions:
  7. You can also try the following to see what errors you get:
    • Comment out data assignements (Id etc) for functions.
    • Stop the Server channel.
  8. Feel free to modify the the code if you wish, you can always rollback to the initial commit.
  9. If you are interested you can also look at the code in the iguana/client module, but it is not necessary as the only as you will never need to change it.

Note: Like any software program this code has bugs. For example the search functions return an error if your search returns no rows:

Technically this may not even be a bug — but it is certainly not the best way to handle an empty search result. However the error message from the default error handling (built into the server framework) does give a good clue as to what is happening, and makes it easy to find the issue.

 

 

Leave A Comment?