Defining your first API

This article is outdated. Please click here to see the newer version.

In this article, we will walkthrough defining your first API on APIMATIC. 

The following covers the following aspects:

  1. Creating a simple API
  2. Defining endpoints
  3. Using models as types
  4. Generating SDKs

For our running example, we will use a simple calculator as our API. 

We will model the API described below

 

Calculator API

Base URI: https://examples.apimatic.io/apps/calculator
Authentication : None

 

The calculator API is a simple API that can consists of the following endpoints:

 

GET /{operation}?:x&:y

Calculates the expression based on the operator and x and y. e.g /sum?x=5&y=5 returns 10.


Operation
[String] Can be : "SUM", "SUBTRACT", "DIVIDE", "MULTIPLY"
x
[Precision]The first arugment to the operation
y
[Precision]The second arugment to the operation

 

Our first API

We need to define a API Entity so that we can specify endpoints and other details for our calculator webservice. This can be done via `My APIs` > `Create New API`. For our example, the details could be as follows.

 

Defining our endpoints

This can be done via the side menu, `Endpoints` > `New Endpoint`. For our example, the details could be as follows:

Then we add the parameters as follow:

 

 

Note: Take special note of how we defined operation parameter as 'Template'. This corresponds to the template parameter in our endpoint url : /{operation}

P1: Using models as types

Defining models is a effective way to improve the usability of the SDK. Looking back at our endpoint, we notice that our 'operation' parameter has a finite possible values. 

We can represent the 'operation' parameter as a model that encapsulates various operation attributes. From the side menu, select `Models` > `New Model`. For our example, the description of the model could be as follows:

Next we configure the fields of our model as shown below:

Finally, save the new Model.
 

P2: Using models as types

To use the Operation Type model defined previously, we update our endpoint as follows:

Finally, save the endpoint.
 

Generating SDKs

Now that we have defined our API, from our Registered APIs page press "Generate" on our API. This will first validate our API Definition and present the SDK platforms for generation.

 

Simply select the platform and you have just downloaded your first APIMATIC generated SDK!

 

The completed API Description is attached below. You can import this to your account to experiment.

Have more questions? Submit a request

Comments