Paths are endpoints (resources) that the 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.
Operations are defined for each (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.
This tutorial shows 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.
Operation ID
An Operation ID (operationId) is an optional and unique string that is used to identify an operation. When providing IDs, ensure that these IDs are unique among all operations described in the 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 were 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, assign a Security Scheme that was 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 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
There are two options to select from:
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 different name=value pairs 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.
Path Source Tab
The path source defines the source operation of the API.
Flow:
To select a flow that was previously created, select the Flow Tab. Click on the input field. Select the relevant flow in the dropdown list.
Processing Mode:
Sync Mode – is automatically defined.
Async Mode – only available when using the PUT, PATCH or POST method.
Return Source:
Select a Return Source type from the dropdown list from one of Auto, Record, Result, or Output.
Output Content Type:
Select an Output Content type from the dropdown list from one of many different types available.
Output Schema:
Enter the schema path to be used.
Override Output Content Type Header:
Override Output Content Type header sent in the response.
Useful Tutorials
Revisit the Getting Started page for a refresher.
Read more about the API Builder here.