Software AG Products 10.7 | Using API Gateway | APIs | Creating an API from Scratch | Creating a REST API
 
Creating a REST API
You must have the API Gateway's manage APIs or activate/deactivate APIs functional privilege assigned to perform this task.
You can create a REST API from scratch by providing the basic information, technical information, and defining the resources and methods as required.
*To create a REST API from scratch
1. Click APIs in the title navigation bar.
A list of all existing APIs appears.
2. Click Create API.
3. Select Create from scratch.
4. Select REST.
5. Click Create.
The Basic information page of the Create REST API wizard appears.
6. Provide the following information in the Basic information section:
Field
Description
Name
Name of the API.
Version
Version of the API being created.
Team
Team to which the API must be assigned.
This option is visible only if you have enabled the Teams feature.
You can select more than one team. To remove a team, click the icon next to the team to be removed.
Maturity state
Maturity state of the API.
Available values are: Beta, Deprecated, Experimental, Production, Test.
The available values depend on the Maturity states configured in the apiMaturityStatePossibleValues property under Administration > Extended settings section.
API grouping
Group under which the API would be categorized.
Available values are: Finance Banking and Insurance, Sales and Ordering, Search, and Transportation and Warehousing.
The available values depend on the groups configured in the apiGroupingPossibleValues property under Administration > Extended settings section.
Tags
Keywords for categorizing, identifying, and organizing APIs. You select from the list of existing tags or create new tags.
Description
Description of the API.
7. Click Continue to provide technical information for this API >.
Note:
Click Save to save the API at this stage and close the Create REST API wizard.
8. Provide the details of the servers that serve the API in the Add server details section.
a. Click Add server and provide a Server URL and Description.
You can include variables in the server URL by enclosing them in curly braces. These variables are added to the list of variables. However, you have to edit these variables to add a default value, and optionally one or more values and a description.
b. Click Add variables and provide the following values:
*Name
*Description
*Default
*Value
Note:
Click + to add the value that you have entered.
c. Click Add to add the variable.
9. Click Add Parameter and provide the following information to add the API-level parameters.
Field
Description
Name
Name of the parameter.
Reference
If you want to reuse a parameter defined on the Components page, select the parameter from the drop-down list.
Description
Description of the parameter.
Type
Specifies the parameter type.
Available values: Query-string, Header, Cookie.
Data type
Specifies the data type.
Available values: String, Date, Date time, Integer, Double, Boolean, File.
Required
Specifies the parameter is required if selected.
Repeat
Select if the input parameter is of type array.
Value
Specifies the possible values.
Note:
You need to define parameters only for data that you want API Gateway to process.
10. Type a Service registry display name.
By default, the API is displayed in service registries with the name: APIName_Version. If you want the API to be displayed in the service registries with a different name, you can type the name here.
11. Click Continue to provide Resource and methods for this API>.
Note:
Click Save to save the API at this stage and close the Create REST API wizard.
12. Add resources to the API using the Resources and methods page:
a. Click Add Resources and provide the following information:
Field
Description
Resource name
Name of the resource.
This is the display name of the resource and resource path is used for execution.
Resource path
Specifies the path of the resource.
The resource path should contain a "/".
Description
Description of the resource.
Supported methods
Select the methods that are supported by the API: GET, HEAD, POST, PUT, DELETE, PATCH.
b. Click Add.
The resource is added. You can multiple resources, if required.
c. Add Tags.
d. Click Add Resource Parameter and provide the following information:
Field
Description
Name
Name of the parameter.
Reference
If you want to reuse a parameter defined on the Components page, select the parameter from the drop-down list.
Description
Brief description of the parameter.
Type
Specifies the parameter type.
Available values: Path, Header, Query-string, Cookie.
Data type
Specifies the data type.
Available values: String, Date, Date time, Integer, Double, Boolean, File.
Required
Specifies the parameter is required if selected.
Repeat
Select if the input parameter is of type array.
Value
Specifies the possible values for the parameter.
e. Click + Add to add the resource parameter.
13. For each supported method that you have added for a resource, provide the following information:
a. Common information
Field
Description
Description
Type a description for the operation.
OperationId
Type an operation Id.
Tags
Type or select the keywords that you want to add to the operation.
b. Method parameters
Field
Description
Name
Name of the parameter.
Reference
If you want to reuse a global parameter defined on the Components page, select the parameter from the drop-down list.
Description
Brief description of the parameter.
Type
Specifies the parameter type.
Available values: Query-string, Header, Cookie.
Data type
Specifies the data type.
Available values: String, Date, Date time, Integer, Double, Boolean, File.
Required
Specifies the parameter is required, if selected.
Repeat
Select if the input parameter is of type array.
Value
Specifies the possible values for the parameter.
c. Requests.
You can select an existing global request defined on the Components page or specify a new request. To create a new request, select New request.
To add a new request that has to be processed, click Add Request + and provide the following information:
*Content type. Select one and click Add.
*Schema. Type a schema in the text box or select an existing schema from the Select a Schema list. You can also click Add global schema and create a new global schema on the Components page. After creating the global schema you can select it from the Select a Schema list.
*Sample. Type a sample for selected schema. This sample can be used for API mocking, if required.
To use an existing global request to process a request, select Global request and provide the following information:
*Name.
*Reference. Select one and click Add.
d. Responses.
First, add a status code using the Status Code drop-down list. Next, click on the status code to select it. For the selected status code, you can select an existing global response defined on the Components page or type a new response. To enter a new response, select New response and define the response by adding a schema and a sample for the response body, header parameters, and links.
Note:
You can also define the response for an HTTP status code series, such as 2** or 4**.
To define a new response for the selected status code, click Add response + and provide the following information:
*Content type. Select one and click Add.
*Schema. Type a schema in the text box or select an existing schema from the Select a Schema list. You can also click Add global schema and create a new global schema on the Components page. After creating the global schema you can select it from the Select a Schema list.
*Sample. Type a sample for selected schema. This sample can be used for API mocking, if required.
To use an existing global response, select Global response and provide the following information:
*Name. Name of the response.
*Reference. Select one and click Add.
To add a header parameter, click + Add method parameter and provide the following information to add a method parameter:
Field
Description
Name
Name of the parameter.
Reference
If you want to reuse a global parameter defined on the Components page, select the parameter from the drop-down list.
Description
Brief description of the parameter.
Type
Specifies the parameter type.
Available values: Header.
Data type
Specifies the data type.
Available values: String, Date, Date time, Integer, Double, Boolean, File.
Required
Specifies the parameter is required if selected.
Repeat
Select if the input parameter is of type array.
Value
Specifies the possible values for the parameter.
Click + in the Value text box to add a value to the list, and click Add to add the header.
To add a link, click + Add links and enter the following information to add a link:
*Name. Name of the link.
*Description. Description for the link.
*Link. You can add a new link or select an existing global link that is defined on the Components page.
To add a new link, select New link and provide the following information:
*Type. Select OperationId for local operations only. OperationRef can be used for both local and external operations.
*Value. If Type is OperationRef, provide a reference to the target operation using the JSON Reference syntax (using by the $ref keyword); and if the Type is OperationId provide the OperationId of the target operation.
*Parameters. Specify the parameters of the target operation that are required to follow the link. Enter a Name and Value, and click Add.
*Request body. Type a request body only if the target operation has a body. Define the contents of the body of the target operation.
To include an existing global link, select Global link and then select an existing global link from the Reference drop-down list.
e. Callbacks. You can add the callbacks that are supported by the method. You can add new callbacks and select existing global callbacks.
Note:
For more information about using callbacks to develop asynchronous APIs, see Asynchronous APIs in Overview. For more information on defining and using callbacks in API Gateway, see Overview of Creating a REST API from Scratch.
To specify a new callback, click + Add callbacks and define the callback:
*Name. A name for the callback resource.
*Click + Add resources and provide details of the API that serves as the callback API.
Note:
The user interface and procedure for defining a callback is similar to defining a resource and methods within the resource.
To include a global callback defined on the Components page, provide the following information:
*Name. Name of the callback resource.
*Reference. If you want to reuse a global callback defined on the Components page, select the callback from the drop-down list and click Add.
14. Click Continue to provide Mocking information for this API>.
Note:
Click Save to save the API at this stage and close the Create REST API wizard.
The API mocking page appears. API mocking is not enabled for a new API. You must edit the API and enable API mocking after creating the API.
15. Click Continue to define API components for this API>.
Alternatively, you can click Components.
Note:
Click Save to save the API at this stage and close the Create REST API wizard.
16. Define the reusable elements that you want to reuse in other pages of the Create REST API wizard.
An API may have several elements that are common across resources and methods, such as schemas for response bodies. You can place such common elements in the Components section and reference them using the $ref alias.
a. In the Schemas section, click + Add schema and provide the following information:
Field
Description
Name
Name of the schema.
Value
Specifies the schema type.
Available types:
*Inline schema. Type the request and response values for the schema in the text box.
*Upload schema. Click Browse and upload a schema file that you have from a saved location.
Action
Click to add the schema.
Click + Add to add the schema component.
b. In the Parameters section, click + Add parameter and provide the following information:
Field
Description
Name
Name of the parameter.
Description
Description of the parameter.
Type
Specifies the parameter type.
Available values: Path, Query-string, Header, and Cookie.
Data type
Specifies the data type.
Available values: String, Date, Date time, Integer, Double, Boolean, and File.
Required
Specifies the parameter is required if selected.
Repeat
Select if the input parameter is of type array.
Value
Specifies the possible values for the parameter.
Click + Add to add the parameter component.
c. In the Headers section, click + Add header and provide the following information:
Field
Description
Name
Name of the header.
Description
Description of the header.
Type
Specifies the header type. This is fixed as Header for headers.
Data type
Specifies the data type.
Available values: String, Date, Date time, Integer, Double, Boolean, and File.
Required
Specifies the header is required if selected.
Repeat
Select if the input parameter is of type array.
Value
Specifies the possible values for the header.
Click + Add to add the header component.
d. In the Examples section, click + Add examples and provide the following information:
Field
Description
Name
Name of the example.
Summary
Description of the example.
Value
The content of the example.
Click + Add to add the example component.
e. In the Links section, click + Add links and provide the following information:
Field
Description
Name
Name of the link.
Description
Description of the link.
Type
Specifies the link type: OperationId or OperationRef.
Value
Path to the target operation or a reference to the target operation.
Parameter name
Name of the parameter to pass as a parameter to the target operation.
Parameter value
Value for the parameter. Click + Add to add the parameter. You can additional parameters if required.
Request body
Payload of the request sent to the target operation.
Click Add to add the link component.
f. In the Callbacks section, click + Add callback and provide the following information:
a. Type a name for the callback.
b. Click + Add resources.
c. Type the Callback path.
d. Select the supported methods.
e. Click Add.
f. For each method that you have just added, complete the next two steps.
g. Click + Add Resource Parameter and add the required resource parameters. The procedure for adding resource parameters is given in Step 11d.
h. Define the selected methods. The procedure for defining methods is given in Step 12.
g. In the Request Bodies section, click + Add request and provide the following information:
Field
Description
Name
Name of the request.
Content type
Select a content type from the list.
Schema
Select an existing schema from the list.
Sample
Type a sample of the schema.
Click Add to add the request component.
h. In the Responses section, click + Add Response and provide the following information:
Field
Description
Name
Name of the response.
Content type
Click Add.
Schema
Select an existing schema from the list.
Sample
Type a sample of the schema.
Header Parameter
Click + Add Header Parameter and provide the required information. Then, click + Add to add the header parameter.
Links
Click + Add Links and provide the required information. Then, click Add to add the link.
Click Add to add the response component.
17. Click Continue to provide API documents for this API>.
Note:
Click Save to save the API at this stage and close the Create REST API wizard.
The Documentation page appears.
18. Type a display name and click Browse to select a file.
19. Click + Add to upload the file and add a new row.
20. Click Save to save your changes and create the API.