Create a REST API¶

Follow the instructions below to create a new REST API artifact in the Micro Integrator for Visual Studio Code extension (MI for VS Code).

Instructions¶

Create the API artifact¶

Launch Visual Studio Code with the Micro Integrator for VS Code extension (MI for VS Code) installed.

Info

Follow the Install Micro Integrator for VS Code documentation for a complete installation guide.
Create an integration project.
Go to Micro Integrator Project Explorer > APIs.

Hover over APIs and click the + icon that appears to open the Synapse API Artifact creation form below.

In the interface that opens, provide details for the synapse API artifact.

Parameter	Description
Name	Name of the synapse API artifact.
Context	The context for the REST API. For example, `/healthcare`. Note It is not recommended to use the same API context in multiple APIs. The API context should be unique for each API. It is also not recommended to use `/service` as API context because it is preserved for Proxy services.
Generate API From	Select one of the given options: None: This option is selected by default. Use it to create a new REST API artifact from scratch. From OpenAPI definition: Select this option to generate the REST API artifact from an existing Swagger definition (YAML/JSON file). The Synapse configuration (XML) of the REST API will be generated using the Swagger definition. From WSDL file: Select this option to generate Synapse API from a WSDL endpoint.

If you selected None in the previous step, you can start creating an API from scratch.

If you selected From OpenAPI definition in the previous step, enter the details of your custom Swagger file:

Parameter	Description
Swagger File	Click Select Location and select a file for OpenAPI definition. This field is required.
Save Swagger Definition	Check this to save the Swagger definition. The Swagger definition will be saved to this registry.

If you selected From WSDL file in the previous step, enter the following information:

Parameter	Description
WSDL Type	Select File to generate API from a WSDL file or a Zip file containing a valid WSDL file, or select URL to generate the API using a remote WSDL file.
WSDL File	Browse and select the WSDL File or Zip file that contains a valid WSDL file.
WSDL URL	Give the remote location of the SOAP Service WSDL File as a valid URL.
SOAP Endpoint	Give the actual SOAP Backend URL. (This should return a valid WSDL when invoked with `?wsdl`.)

Note

Current SOAP to REST Generation has the limitations mentioned here.
All the generated REST Services are not production-ready and users need to review them manually using MI for VS Code and edit if needed.
Since having . (dot) in XML element names is not a best practice, you may need to manually change the generated soap payload to include the . (dot).

Once you complete the API Form, click Create.

The REST API is created inside the /src/main/wso2mi/artifacts/apis folder of your integration project.

If you have provided a custom Swagger definition file (YAML), it is stored in the /src/main/wso2mi/resources/api-definitions folder of your integration project.

Once you create the REST API, it will be available on the Service Designer under Available Resources.

Add new API resources¶

When you create the API, an API resource is created by default. If you want to add a new resource:

Click + Resource on the Service Designer to open the Add API Resource pane.
Add the required details.
Click Create.

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 resources definitions will be dispatched to the default resource of the API. In the following example, if a DELETE request is received by SampleAPI on the /payments URL, the request will be dispatched to the default resource as none of the resources in SampleAPI are configured to handle DELETE requests.

SampleAPI

<api name="SampleAPI" context="/payments">
<resource url-mapping="/list" methods="GET" inSequence="seq1"/>
<resource uri-template="/edit/{userId}" methods="PUT POST">
    <inSequence>
         <log/>
         <send>
              <endpoint key="BackendService"/>
         </send>
    </inSequence>
</resource>
<resource inSequence="seq2"/>
</api>

Update metadata¶

When you create the API artifact from MI for VS Code extension, the metadata files will be created and stored under the <PROJECT_NAME>/src/main/wso2mi/resources/metadata folder.

Note

You can view the below folder structure by switching to the VS Code default Explorer view.

Design the integration¶

On the Service Designer, click on the API resource and go to the Resource View.
Add the required mediators and connectors to the API resource and design the integration flow.

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

Update properties¶

To update API level properties:

On the Service Designer, click on the API resource to go to the Resource View of the API resource.

You will now see the graphical view of the API with its default API Resource.
Click the Edit icon to edit the API resource.
Specify values for the required resource properties:
Click Update.

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

Use the Source View¶

Click the Show Source (</>) icon located in the top right corner of the VS Code to view the XML-based synapse configuration (source code) of the API.

You can update the API using this view.

Use the Swagger View¶

Go to Service Designer.
Click OpenAPI Spec to view the API definition of your API.

You can interact with the API using the Swagger View.

Note

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

Learn more about REST APIs

Follow our examples on REST APIs: