Defining your first API

In this article, we will walk you through describing your first API on APIMATIC.

For our running example, we will use a simple calculator as our API. We will model the API described below.

Sign-up Required   You will need to sign-up for an APIMATIC account to follow this tutorial. Signing-up is free.

Calculator API

Base URI:
Authentication : None

The calculator API is a simple API that consists of a single endpoint:

GET /{operation}?:x&:y

This endpoint returns the sum of two parameters x and y. Example: /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

Creating an API description

To create a new API description, click on Create from the My APIs page and enter some basic required information about your API.

Create API

Once the API is created, click on Edit to open up the API editor.

Edit API

Defining our endpoints

We now need to describe our first endpoint. From the navigation on the left side of the API Editor, click Endpoints > New Endpoint. Fill in the required fields as follows.


We now need to add the parameters for the endpoint.


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

Click on Save Endpoint to save your changes to the API description.

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:


Click on Save Model to save your changes.

P2: Using models as types

Go back to where you defined your endpoint Calculate. To use the Operation Type model defined previously, we need to update our endpoint as follows:


Click on Save Endpoint to save this new change.

Congratulations! You have described your first API successfully. Lets return to the My APIs page and try generating an SDK for this API for your favourite platform.

Have questions? Submit a request.