Create a REST API¶
API creation is the process of linking an existing backend API implementation to the API Publisher, so that you can manage and monitor the API's lifecycle, documentation, security, community, and subscriptions. Alternatively, you can provide the API implementation in-line in the API Publisher itself.
Follow the instructions below to create a REST API using the basic flow:
-
Sign in to the WSO2 API Publisher.
https://<hostname>:9443/publisher
Example:
https://localhost:9443/publisher
Note
The Create API button will only appear for a user who has the
creator
role permission. -
Select REST API from the options available.
-
Click Start from Scratch.
-
Enter API details.
Field Sample value Name PizzaShack Version 1.0.0 Context /pizzashack
The API context is used by the Gateway to identify the API. Therefore, the API context must be unique. This context is the API's root context when invoking the API through the Gateway.
You can define the API's version as a parameter of its context by adding the
{version}
into the context. For example,{version}/pizzashack
. The API Manager assigns the actual version of the API to the{version}
parameter internally. For example,https://localhost:8243/1.0.0/pizzashack
. Note that the version appears before the context, allowing you to group your APIs based on the versions.Endpoint https://localhost:9443/am/sample/pizzashack/v1/api/
The endpoint that you add is automatically added as the production and sandbox endpoints.
Note
The Create & Publish option will only appear when a user who has
publisher
permission adds the details for the Endpoint which is an optional field. -
Click Create to create the API.
If you click Create & Publish
If you click Create & Publish, WSO2 API Manager will automatically create a revision for the API, deploy the revision on the Gateway, and also publish your API to the Developer Portal.
The overview page of the newly created API appears.
-
Go to Develop, Portal Configurations, and click Basic Info.
-
Configure the API design configurations.
Note
By default, All users who have
creator
permission are allowed Publisher Access Control and public Developer Portal visibility. -
Add a tag and press enter.
Let's add a tag named pizza.
Info
Tags can be used to filter out APIs matching specific search criteria. It is a good practice to add tags that explain the functionality and purpose of the API so that subscribers can search for APIs based on the tags.
-
Optionally, select Yes for the Make this the Default Version option.
What happens when an API is the default version?
- The API will be available in the Gateway without a version specified in the Production and Sandbox URLs.
- If required, you can create a new version of an API and set it as the default version.
- This allows the same resources to be invoked in the client applications without changing the API Gateway URL.
- This allows users to seamlessly switch to the new API version without doing any changes to the invocation URL.
- If required, you can create new versions of an API with changes, while keeping the previous version as the default API.
- This allows the existing client applications to be invoked without the client having to change the URLs.
- This allows existing users to still use the old API because that is the default version.
- Users need to explicitly call the respective version that corresponds to the new API to be able to invoke it.
- This provides the ability to run the new API in parallel to the old API; while, also allowing some new users to try out the new API.
-
Click Save.
-
-
Configure the runtime configurations.
-
Click Runtime, which is under the API Configurations section.
Transport Level Security defines the transport protocol on which the API is exposed.
-
If you wish to limit the API availability to only one transport (e.g., HTTPS), deselect the Transport Level Security checkbox.
Both HTTP and HTTPS transports are selected by default.
-
-
Configure the resources.
By default, the API will have five resources with
/*
as the URL pattern.-
Click Resources, which is under the API Configurations section.
-
Modify the resources as follows and click Save to update the resources.
-
Click delete, as shown below, to remove all the existing resources.
-
Select an appropriate HTTP Verb from the dropdown and click (+) to add a new resource.
The newly added resource is displayed as follows.
-
Expand the created GET operation to add details for the Summary and Description and Operation governance sections.
- Add a summary and description for the resource.
-
Update the Security settings as required.
- Turn the security setting off if you want to make a certain operation of the API non-secured and accessible without passing an access token.
- To make the whole API non-secured and fully accessible without an access token, turn the security setting off in all the operations of the API.
-
Add resource parameters if required using the Parameters section.
You can define the following parameter types based on the resource parameters that you add.
Parameter Type Description query
Contains the fields added as part of the invocation URL, which contains the data to be used to call the backend service. header
Contains the case-sensitive names followed by a colon (:) and then by its value that carries additional information with the request, which defines the operating parameters of the transaction. cookie
Operations can also pass parameters in the Cookie header, as Cookie: name=value
. Multiple cookie parameters are sent in the same header, separated by a semicolon and space.body
An arbitrary amount of data of any type is sent with a POST message.
-
-
-
Optionally, view the API definition.
Click API Definition.
The OpenAPI Specification (a.k.a Swagger definition) for the PizzaShack API appears.
Observe Linter results
You can observe results for the Linter rules you create by doing the following.
-
Navigate to the APIM Publisher Portal.
-
Log in using your credentials.
-
On the sidebar, navigate to Develop > API Configuration > API Definition.
-
Click on Edit from the toolbar.
-
Switch to the Linter view by clicking on the LINTER button on the top.
-
You will see the Linter error corresponding to the new rule you enforced.
Now, you have successfully created and configured a REST API. Next, deploy the API, test the API, and finally publish the API.
See Also¶
Learn more on the concepts that you need to know when creating a REST API: