Paths are endpoints (resources) that your API exposes, such as /users or /books, and operations are the HTTP methods used to manipulate these paths, such as GET /books, POST /books or DELETE /book.
For each path, you can define operations (i.e. HTTP methods) that can be used to access that path. A single path can support multiple operations, for example, GET /users to get a list of users and POST /users to add a new user.
In this tutorial, you learn how to create two paths, one parameterized and one not. Each path will include a Definition and a Link to an associated Synatic flow.
Path Definition Tab
The path definition includes a summary of the API path function and a full description.
The associated parameters include:
Operation ID
An Operation ID (operationId) is an optional and unique string that is used to identify an operation. If you provide an ID then you should ensure that these IDs are unique among all operations described in your API.
Some common use cases for the operationId are:
Typical labels could be GetAPI or PutAPI
Some code generators may use this value to name the corresponding methods in code.
Links can refer to the linked operations by operationId.
Tags
In the Tags parameter, you can assign tags that you created previously in the Tags tab.
Click on the Add Tag field and type the first letter of the existing tag.
Select a Tag listed in the dropdown.
Security Scheme
In the Security Schemes parameter, you can assign a Security Scheme that you created previously in the Security Schemes tab.
Click on the Security Schemes field and type the first letter of the existing Security Schemes.
Select a Security Scheme listed in the dropdown.
Path Parameters
A path parameter is defined as being used in line with a path e.g. /onebook/{YearParam} and other attributes as necessary.
The parameter name must be the same as specified in the path.
Each path parameter must be substituted with an actual value when the client makes an API call.
Parameters
These parameters can be one of two that you may select.
1. Query Parameters
Query parameters are the most common type of parameters.
They appear at the end of the request URL after a question mark (
?), with differentname=valuepairs separated by ampersands (&).Query parameters can be required and optional.
2. Header Parameters
An API call may require that custom headers be sent with an HTTP request.
You can define custom request headers as
in: headerparameters.
Path Source Tab
The path source defines the source operation of the API.
Flow
To select a Synatic flow previously created, select the Flow Tab.
Click on the input field.
Select the relevant flow in the dropdown list.
Flow Parameters
To select the internally assigned flow parameter:
Click on the From Path field and the relevant value.
It should look something like reqParameters.YearParam (as was created).
Processing Mode
The Synchronous mode is automatically defined.
Return Source
Select a Return Source type from the dropdown list from one of Auto, Record, Result, or Output. For this tutorial, select Auto.
Enforce Input Schema
Select this checkbox to enforce the application of the schema you defined,
Output Content Type
Select an Output Content type from the dropdown list from one of many different types available. For this tutorial, select JSON Array.
Output Schema
Enter the schema path you want to use.
Coerce Schema
Select this option to force the use of your selected schema path.
Watch the video below to learn how to create a Path.
Path Flows
Creating Synatic Flows is discussed in the following Flow tutorial.
Path Flow for GET /allbooks
The following video illustrates creating a flow to get all records.
Set up a flow to connect to the database.
Extract and display all records.
Path Flow for GET /onebook{YearParam}
The following video illustrates creating a flow to specific records.
Set up a flow to connect to the database and extract books published in a specific year.
Create a parameter to get capture the Year value.
Extract and display records as per the Parameter value.
Useful Tutorials
Revisit the Getting Started page for a refresher.
Read more about the API Builder here.