Defining an API
In this article, we will walk you through describing your first API on APIMatic. Generally, to get started, you can either use APIMatic's sample API (Create > Use Sample API) or define one from scratch. For this walkthrough, we will take a simple calculator API and model it step by step using the editor.
You need to be signed in from an APIMatic account to follow this tutorial. Signing-up is free.
Calculator API
The calculator API is a simple API that consists of a single endpoint that supports SUM, SUBTRACT, DIVIDE and MULTIPLY operations:
GET /{operation}?:x&:y
For sum operation, this endpoint returns the sum of two parameters x and y e.g. /sum?x=5&y=5 returns 10. The complete list of input parameters is described in detail below:
| Variable | Type | Type Info |
|---|---|---|
| Operation | String | Allowed values: SUM, SUBTRACT, DIVIDE, MULTIPLY |
| x | Precision | The first argument to the operation |
| y | Precision | The second argument to the operation |
The API is served at base URI http://examples.apimatic.io/apps/calculator and does not require any authentication.
Creating an API definition
To create a new API definition, click on Create from the Dashboard and enter some basic required information about your API.
Once the API is created, click on Edit to open up the API editor.
Defining endpoints
We are now going to describe our first endpoint. From the navigation on the left side of the API Editor, click Endpoints > New Endpoint.
In the Endpoint Settings, start filling basic details of the endpoint as shown in the image below e.g. we will name the endpoint Calculate. Grouping helps collate similar endpoints but since we have only one endpoint in this case we can simply group it under Simple Calculator. The endpoint is called using GET HTTP method at route /{operation} relative to the Base URL so the field for Route is filled accordingly. The endpoint is expected to return the result of the operation as a precision number so the Response Type is selected as Precision. You can also provide an optional description of the endpoint in the Description field.
For more details about describing endpoints, you can check out our detailed documentation on API Endpoints .
Now we can start describing all input parameters of the Calculate endpoint.
Parameter operation corresponds to the segment /{operation}of the endpoint route and therefore, will be defined as a Template parameter whose value will be substituted in endpoint URL at the time of calling the endpoint. We will define a special type Operation Type for this parameter which is described later in this walkthrough. To see how to add other details of the parameter check out the image below:
Define number arguments x and y as Query parameters as shown below:
Click on Save Endpoint to save your changes to the API definition.
You can learn more about describing endpoints in our Endpoints documentation.
P1: Defining models as types
Defining models is an effective way to improve the usability of the SDK. Looking back at our endpoint, we notice that our operation parameter has a finite set of possible values: SUM, SUBTRACT, DIVIDE, and MULTIPLY. To describe this, we can create a model of type Enumeration that supports fixed values of string or number type. From the side menu, select Types > New Type. Let's name the model as Operation Type.
Fill in the required information of the model as shown below::
Next we configure the fields of our model as shown below:
Click on Save Model to save your changes.
For more details about describing models, you can check out our detailed documentation on Models.
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. Let's return to the Dashboard and try generating an SDK for this API for your favourite platform.