Create an API

Follow these instructions to create an API artifact in the Micro Integrator for Visual Studio Code extension (MI for VS Code).

Create an API artifact

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

2. Create an integration project.

   Hereafter, this project will be referred to as <PROJECT_NAME>.

3. To add a new API, go to Micro Integrator Project Explorer > APIs.

4. Hover over APIs and click the + icon that appears to open the API Form.

5. Provide details for the API artifact.

   Field	Description
   Name	The name of the API artifact.
   Context	The context for the API. For example, /healthcare. Note This value will be automatically populated with the same value you provided for the API Name, or you can update it with a different name. The API context should be unique for each API. It is not recommended to use /service as the 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 API artifact from scratch. From OpenAPI definition: Select this option to generate the API artifact from an existing Swagger definition (YAML/JSON file). The Synapse configuration (XML) of the API will be generated using the Swagger definition. From WSDL file: Select this option to generate Synapse API from a Web Services Description Language (WSDL) endpoint.

   • If you selected None under Generate API From, you can start creating an API from scratch.

     

   • If you selected From OpenAPI definition under Generate API From, 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.

     

   • If you selected From WSDL file under Generate API From, 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

     • The current SOAP to REST generation has some limitations.
     • Go to the Limitations of SOAP to REST Feature documentation for more details on these limitations.
     • All the generated REST services are not production-ready and require manual review and necessary edits using MI for VS Code.
     • Additionally, since using a dot . in XML element names is not considered a best practice, you may need to manually modify the generated SOAP payload to remove or adjust the dot notation.

6. Once you complete the API Form, click Create.

Info

You can switch to the default Visual Studio Code Explorer to view the folder structure.

• The newly-created API will be stored in the <PROJECT_NAME>/src/main/wso2mi/artifacts/apis folder of your integration project.
• A Swagger file for the API will be generated in the <PROJECT_NAME>/src/main/wso2mi/resources/api-definitions folder.

• The created APIs will be available in the MI Overview.

  

• The created API resources will be available in 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:

1. Click + Resource on the Service Designer to open the Add API Resource pane.

2. Add the required details.

3. Click Create.

   

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>

Design the integration

1. Open the Resource View of the API resource.

   1. Go to MI Project Explorer > APIs.
   2. Under the API you created, click the API resource to open the Resource View of the API resource.

2. Click on the + icon below the API resource to open the mediator palette.

3. Add the required mediators and connectors to the API resource and design the integration flow.

Update configurations

Update the API configurations

1. Go to MI Overview.

2. Under APIs, select the API you want to edit. This will open the Service Designer.

3. On the Service Designer, click the Edit icon to edit the API.

   

   This will open the Edit API interface.

4. Once you edit, click Save Changes.

   See the complete list of API configurations you can configure.

Update the API resource configurations

1. Go to MI Overview.

2. Under APIs, select the API you want to edit. This will open the Service Designer.

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

4. Click the Edit icon to edit the API resource.

   

   This will open the Edit API Resource interface.

5. Once you edit, click Update.

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

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.

You can update the API using this view.

Swagger View

1. Go to Service Designer.

2. 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 created the API by adding a custom Swagger definition, this view displays the API's default Swagger definition, not the custom one you have added.

Learn more about APIs

Follow our examples on APIs:

• Using a Simple Rest API
• Working with Query Parameters
• Exposing a SOAP Endpoint as a RESTful API
• Exposing Non-HTTP Services as RESTful APIs
• Handling Non Matching Resources
• Handling HTTP Status Codes
• Manipulating Content Types
• Securing a REST API
• Special Cases