Creating a REST API

Software AG Products 10.5 | 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. 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. Enter 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.
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 will be 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 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: 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, enter 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 enter a new request, select New request and provide the following information:

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 enter 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.

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 enter 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 enter 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: Enter 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.
Schema type	Specifies the schema type. Available types: Inline schema and Upload schema.
Value	Specifies the value for the schema type selected. For an inline schema, type the request and response values. For an external schema, click Browse to upload a 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 that needs to be passed 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	You can also select an existing schema.
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	You can also select an existing schema.
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.