Creating REST Provider

This section explains the process of creating web service provider service for RESTful Web Service. 

Follow the steps below to create a REST Provider:

1. Click Configure > WEB SERVICES > REST Provider.

2. Click Create REST Provider. 

3. In Create REST Provider window, type the name and description of the new Web Service Provider service in the Name and Description fields respectively.

4. In the Character Set Encoding field, enter the character set encoding for the REST Provider that you are creating.

   By default, this field displays the character set encoding that you have defined at the application level. In case the character set encoding for the REST Provider that you are creating is other than the default one (UTF-8), you can change this in the Character Set Encoding field.

5. Select either Process Flow or Template based on how you want to publish this REST Provider.  

   The REST providers that are published as Process Flows and set to be executed in Sync mode bypass the queue and get executed immediately.

6. In the Definition Mode field, do either of the followings:

   1. Select Manually if you want to define the REST Provider manually, and skip to step 7.
      

   2. Select Import Definition File (OAS 3.0) if you want to define the REST Provider using a Swagger YAML/JSON file. 

      A sample Swagger YAML file Expand source

      openapi: 3.0.0
      servers:
        - description: SwaggerHub API Auto Mocking
          url: https://virtserver.swaggerhub.com/maheshyadava/TestAPI/1.0.0
      info:
        description: This is a simple API
        version: "1.0.0"
        title: Simple Inventory API
        contact:
          email: you@your-company.com
        license:
          name: Apache 2.0
          url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
      tags:
        - name: admins
          description: Secured Admin-only calls
        - name: developers
          description: Operations available to regular developers
      paths:
        /inventory:
          get:
            tags:
              - developers
            summary: searches inventory
            operationId: searchInventory
            description: |
              By passing in the appropriate options, you can search for
              available inventory in the system
            parameters:
              - in: query
                name: searchString
                description: pass an optional search string for looking up inventory
                required: false
                schema:
                  type: string
              - in: query
                name: skip
                description: number of records to skip for pagination
                schema:
                  type: integer
                  format: int32
                  minimum: 0
              - in: query
                name: limit
                description: maximum number of records to return
                schema:
                  type: integer
                  format: int32
                  minimum: 0
                  maximum: 50
            responses:
              '200':
                description: search results matching criteria
                content:
                  application/json:
                    schema:
                      type: array
                      items:
                        $ref: '#/components/schemas/InventoryItem'
              '400':
                description: bad input parameter
          post:
            tags:
              - admins
            summary: adds an inventory item
            operationId: addInventory
            description: Adds an item to the system
            responses:
              '201':
                description: item created
              '400':
                description: 'invalid input, object invalid'
              '409':
                description: an existing item already exists
            requestBody:
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/InventoryItem'
              description: Inventory item to add
        /report:
          get:
            tags:
              - admins
            summary: searches reports
            operationId: searchReport
            description: |
              By passing in the appropriate options, you can search for
              available reports in the system
            parameters:
              - in: query
                name: searchString
                description: pass an optional search string for looking up report
                required: false
                schema:
                  type: string
              - in: query
                name: skip
                description: number of records to skip for pagination
                schema:
                  type: integer
                  format: int32
                  minimum: 0
              - in: query
                name: limit
                description: maximum number of records to return
                schema:
                  type: integer
                  format: int32
                  minimum: 0
                  maximum: 50
            responses:
              '200':
                description: search results matching criteria
                content:
                  application/json:
                    schema:
                      type: array
                      items:
                        $ref: '#/components/schemas/ReportItem'
              '400':
                description: bad input parameter
      components:
        schemas:
          InventoryItem:
            type: object
            required:
              - id
              - name
              - manufacturer
              - releaseDate
            properties:
              id:
                type: string
                format: uuid
                example: d290f1ee-6c54-4b01-90e6-d701748f0851
              name:
                type: string
                example: Widget Adapter
              releaseDate:
                type: string
                format: date-time
                example: '2016-08-29T09:12:33.001Z'
              manufacturer:
                $ref: '#/components/schemas/Manufacturer'
          Manufacturer:
            required:
              - name
            properties:
              name:
                type: string
                example: ACME Corporation
              homePage:
                type: string
                format: url
                example: 'https://www.acme-corp.com'
              phone:
                type: string
                example: 408-867-5309
            type: object
          ReportItem:
            properties:
              name:
                type: string
                example: ACME Corporation
              quarter:
                type: string
                example: 'first, second, third, fourth'
              sales:
                type: number
                example: 12,5000
            type: object

      If selected, follow the steps i through iv.
      
      1. Click Choose File.
         

      2. Browse to select the Swagger file to be uploaded.

         Make sure that the Swagger file you upload is in YAML or JSON format and adheres to the OAS 3.0 standards.

      3. Select a resource end path in the Select Resource End Path field.

         The Select Resource End Path field lists the endpoints mentioned in the Swagger file.

      4. Follow the rest of the steps from step 7 onwards.

7. Select the Asynchronous check box if you want the Transaction based on this Template (with REST Webhook as a source) to be asynchronous.

   This field is available only when you publish the REST Provider as a Template.  

8. Select Enable SSL check box if you want the REST Provider service to offer a SSL security.

   If you select Enable SSL, this REST provider will be published over SSL and use SSL configuration (KeyStore, TrustStore etc.) defined for the port that you select in the next step.

9. In the Select Port field, select the port on which you want to publish the REST provider.

   All the ports that are available on API Gateway will be visible in this field. You can also define/edit/delete a custom port through an environment variable in values.yaml file. Click here to know how to configure the ports. 
10. In the API Version field, enter the API Version. For example, your API version can be 1.1.

11. In the Resource End Path field, enter the resource end path URL. The URL can be static or dynamic.
    Static URL example: /rest/WeatherForecast
    Dynamic URL example: /rest/{ServiceName} where service name is a variable, for example, WeatherForecast.  

    • This field is available only when you select Manually as the Definition Mode.
    • The variable name in the Dynamic URL must be in the curly braces {}. 

12. In the Process Flow Name field, select a Process Flow to trigger with the REST provider.

    This field is available only when you publish the REST Provider as a Process Flow.  
    1. The selected Process Flow must have Context Source and Context Target activity – GET and DELETE can only have Context Target, whereas PUT and POST can have both Context Source and Context Target activity.
    2. The parameterName attribute of the Context Source should be restRequest.
    3. The parameterName attribute of the Context Target should be restResponse.

13. In the Resource Parameter section, enter the name, default value, and style in the respective fields to define the parameters that you want to pass.

    To pass a parameter as a part of HTTP header, select Header in the Style field corresponding to that parameter.

14. Click Add Method.

15. In the window that opens on your browser, do the followings to add a method to your activity. 
    
    

    1. Select the type of method from the Method Type field. The available methods are PUT, GET, POST, and DELETE. Depending upon the selection of the method type, the content of the Presentation table appears.

       • If you use GET method in the REST provider being published as a Template,
         
         • The Context File Based Routing is not supported.
           
         • You don’t get a REQUEST Type of Presentation. However, for DELETE method you will find the REQUEST Type of Presentation.
       • If you use PUT or POST method, you can select the Delete On Success option to delete the attachments saved after the successful execution of the REST Provider that has been published as a Process Flow.
         

    2. In the Method Parameter section, define the method parameters. Enter the name, default value, and style in the respective fields.

       To pass a method parameter as a part of HTTP header, select Header in the Style field corresponding to that parameter.
    3. In the Presentation section, set the Media Type as application/text, application/xml, or application/json based on your requirement. If you set the Media Type as xml or json, select a Layout (Schema) for the respective media type. 
    4. Set the Status Code for Request, Response, and Fault.
    5. In the Response Header section, define the headers. Type the response header names and values in the respective fields.
    6. Click Save.
       This will add the method in Method Parameter section in the Create REST Provider page.

16. In the Authentication Type field, select the authentication type. The possible values are None, Basic, API Key, Kerberos.

17. In the Security Policy field, select a security policy. 

    You can also edit the selected security policy by clicking , or create a new security policy by clicking icon.
    The security policies corresponding to the selected Authentication Type are listed in this field. For information on how to create a Security Policy, refer to Creating Security Policy for Web Service. 

18. Expand the Advanced Properties section

19. Select a project from the Project field.

20. Click Save.

After you have finished creating the REST Provider:

• You can see its type (Template or Process Flow) under the TYPE column on the REST Provider manage page.
• You can also publish or unpublish the REST Provider from the same page, click here for more details.
• You can add the API Documentation.