Creating a REST API

Follow the instructions given below to create a new REST API artifact.

Tip

If you do not see the features given below in the WSO2 Integrations Studio that you are using, you can get the latest updates.

Instructions

Creating the API artifact

  1. Right-click the Config project in the project explorer and go to New → REST API to open the API Artifact Creation Options dialog box.

  2. In the API Artifact Creation Options dialog box, select one of the given options for creating the API artifact:

    Create A New API Artifact This option is selected by default. Use this option if you want to create the REST API artifact from scratch.
    Generate API using Swagger Definition Selet this option if you want to generate the REST API artifact from an existing Swagger definition (YAML/JSON file). That is, the synapse configuration (XML) of the REST API will be generated using the Swagger definition.
    Import API Artifact Select this option to import an existing REST API configuration (XML definition) that was created using WSO2 Integration Studio.

  3. Click Next to go to the next page and enter the relevant details.

    • If you selected Create a New API in the previous step, enter the basic details that are required for creating the synapse configuration (XML) of the API:

      Parameter Description
      Name Required.
      The name of the REST API.
      Context Required.
      The context for the REST API. For example, /healthcare.
      Path to Swagger Definition Enter the path to a custom Swagger definition (YAML/JSON file) that is stored in a registry project in your workspace.

      Once this API is created and deployed in the Micro Integrator, users will be able to access this custom Swagger definition in addition to the default Swagger definition of the API.

    • If you selected Generate API using Swagger Definition in the previous step, enter the details of your custom Swagger file:

      Parameter Description
      Swagger Definition File Required.
      Click Browse and select the Swagger file.
      Swagger Registry Path Click Browse to select an existing registry project in your workspace. The Swagger definition will be saved to this registry.

      If you don't have an existing registry project, click Create new project to add a new registry project to your workspace.

    • If you selected Import API Artifact in the previous step, enter the following information:

      Parameter Description
      API Configuration File Required.
      Click Browse and select the REST API configuration file.

  4. Click Finish. 

    • The REST API is created inside the src/main/synapse-config/api folder of your Config project.
    • If you provided a custom Swagger definition file (YAML), it is now stored in the registry project.

Designing the integration

When you open the REST API from the Config project in the project explorer, you will see the default Design view as shown below.

Drag and drop the required integration artifacts from the Palette to the API resource and design the integration flow.

You can also use the Source view or the Swagger Editor to update the API configuration.

Adding new API resources

When you create the API, an API resource is created by default. If you want to add a new resource, click API Resource in the Pallet and simply drag and drop the resource to the REST API.

Info

About the default API Resource

Each API can have at most one default resource. Any request received by the API but does not match any of the enclosed resource definitions will be dispatched to the default resource of the API. In case of API_3, a DELETE request on the URL “/payments” will be dispatched to the default resource as none of the other resources in API_3 are configured to handle DELETE requests. If you go to the Source view, the default resource will be as follows: 

<api context="/healthcare" name="HealthcareAPI" xmlns="http://ws.apache.org/ns/synapse">
    <resource methods="GET">
        <inSequence/>
        <outSequence/>
        <faultSequence/>
    </resource>
</api>

Updating properties

To update API-level properties from the Design view:

  1. Double-click the API icon to open the Properties tab for the API.

  2. See the complete list of optional REST API properties you can configure.

To update API resource properties from the Design view:

  1. Double-click the Resource icon to enable the Properties tab for the resource.

  2. See the complete list of API Resource properties you can configure.

Using the Source View

Click the Source tab to view the XML-based synapse configuration (source code) of the API. You can update the API using this view.

Using the Swagger Editor

Click the Swagger Editor tab to view the Swagger definition of your API. You can update the API using the Swagger editor (left panel) and also interact with the API using the Swagger UI (right panel).

Note

If you have added a custom Swagger definition to the API, note that this view displays the API's default Swagger definition and not the custom Swagger definition that you added.

Examples

Top