Core Concepts

Introduction

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 for defining JSON based Web APIs.

And finally we explain how these concepts apply to the typical Design Process when you are 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

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.

Leave A Comment?