Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

API Design First on WSO2 API Manager

DZone's Guide to

API Design First on WSO2 API Manager

Learn how to use the WSO2 API Manager with an API First Design Approach, import a Swagger definition file, and prototype our API.

· Integration Zone ·
Free Resource
CRM integration has become the cornerstone to meeting initiatives across organizations. Explore the top 6 value-driven Salesforce CRM integrations ebook.  

The OpenAPI Specification (formerly Swagger) let us “create the RESTful contract for your API, detailing all of its resources and operations in a human and machine-readable format for easy development, discovery, and integration.” So, using Swagger, we can specify how our API will look, which operations we can perform on it, the expected parameters or payloads, and the format of the responses of the operations.

By having a way to define the contracts, it gives us the ability to quickly design an API and, from this design, prototype it without creating any real backend.

In this post, we are going to see how we can use the WSO2 API Manager with an API First Design Approach while importing a Swagger definition file, and how to prototype our API.

Let’s start.

1. The Swagger File

For this blog post, we are going to create a simple API definition for Test Scores with two resources:

  • GET /scores/{testId}: To retrieve the Score information by the given testId:
    •  { “testId”: 0, “score”: 0 }
  • GET /scores/user/{username}: To retrieve all the test scores for the given username:
    • [ { “testId”: 0, “score”: 0 } ]

We can see the Swagger definition below:

{  
   "swagger":"2.0",
   "info":{  
      "title":"ScoresAPI",
      "description":"API to manage Test Scores",
      "version":"v1",
      "basePath":"/scores"
   },
   "paths":{  
      "/scores/{testId}":{  
         "get":{  
            "description":"Returns the scores for given testId",
            "produces":[  
               "application/json"
            ],
            "parameters":[  
               {  
                  "name":"testId",
                  "in":"path",
                  "description":"The id of the test that the score will be retrieved",
                  "required":true,
                  "type":"integer"
               }
            ],
            "responses":{  
               "200":{  
                  "description":"A Score resource",
                  "schema":{  
                     "$ref":"#/definitions/Score"
                  }
               }
            }
         }
      },
      "/scores/user/{username}":{  
         "get":{  
            "description":"Returns the scores for the given userId",
            "produces":[  
               "application/json"
            ],
            "parameters":[  
               {  
                  "name":"username",
                  "in":"path",
                  "description":"The username of the user",
                  "required":true,
                  "type":"string"
               }
            ],
            "responses":{  
               "200":{  
                  "description":"The list of Score resources",
                  "schema":{  
                     "type":"array",
                     "items":{  
                        "$ref":"#/definitions/Score"
                     }
                  }
               }
            }
         }
      }
   },
   "definitions":{  
      "Score":{  
         "type":"object",
         "properties":{  
            "testId":{  
               "type":"integer"
            },
            "score":{  
               "type":"number",
               "format":"double"
            }
         }
      }
   }
}

2. Using the Swagger File on the WSO2 API Manager

The WSO2 API Manager gives us the ability to create APIs from a Swagger Definition file. Below we can see the steps for publishing an API from a Swagger file.

  • In the Publisher portal, we go to the “Add New API” and select “I have an Existing API,” then select the Swagger file and click “Start Creating”:

Adding The API

  • In the next step, we will see that, for the most part, the information will be filled-in from the Swagger file, such as Title, Version, and the resources, but we need to specify the context. In our example, we will use /scoresapi:

The API Design

  • After that, we go to the Implement tab. In this tab, we have an option to point to an existing backend in the Managed API, or we can have a Prototyped API. In our example of API Desing First, we are going to have a Prototyped API. And we will have an inlined API. When choosing the inline option, it will give us the option to define the response for the resources we defined in the Swagger file:

The API Design

For the inline script, it is basically a script mediator code snippet. For the resource /scores/{testId} we will have the following code snippet:

mc.setProperty('CONTENT_TYPE', 'application/json');
var testId = mc.getProperty('uri.var.testId');
var response = {
  "testId": testId,
    "score": 7.0
    };
    mc.setPayloadJSON(response);

For the resource /scores/user/{username} we will use the following snippet:

mc.setProperty('CONTENT_TYPE', 'application/json');
var username = mc.getProperty('uri.var.username');
var response = [];
response.push({"testId": 123, "score": 7.0});
response.push({"testId": 124, "score": 8.0});
response.push({"testId": 145, "score": 10.0});
mc.setPayloadJSON(response);

And then we click on Deploy as Prototype. After that, the API will be published to the API Store and we can start invoking the APIs:

  • http://localhost:8280/scoresapi/v1/scores/user/admin

The API Design

  • http://localhost:8280/scoresapi/v1/scores/12

The API Design

As we can see, by using the Prototyped APIs we can quickly get an API up and running and all the API consumers can start using the API.

That’s it for today, I hope you enjoyed it.

See you in the next post!

Sync, automate, and notify lead to customer changes across marketing, CRM, and messaging apps in real-time with the Cloud Elements eventing framework. Learn more.

Topics:
integration ,api ,rest ,swagger ,wso2 api manager

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}