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.
Base URI: https://examples.apimatic.io/apps/calculator Authentication : None
The calculator API is a simple API that consists of a single endpoint:
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.
Once the API is created, click on Edit to open up the API editor.
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:
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.