Nav

Design an API

In this tutorial, you design a RAML-based API using API Designer. The API creates a web service for users to order t-shirts and track orders. This API consists of a series of operations that users of your API can call. Each operation maps to a resource. All the operations in this API relate to one of the following resources:

  • /products

  • /orders

Each order has a nested {orderId}/status, which is a sub-resource of orders.

Download the RAML code for this example.

Assuming you have set up the API for ordering T-Shirts, perform these steps to design the API:

  1. Click API Manager to go to the API Administration page.

  2. Click the version number of the T-Shirt Ordering Service project: 1.0.development.

    walkthrough-design-new-a7e5e

    The API version details page appears.

  3. Click Edit in API designer:

    The API Designer appears.

  4. On the line following the version, add a placeholder baseUri for simulating the API. Specify the baseUri as: http://www.tshirt.com/api

    
                
             
    1
    2
    3
    4
    
    #%RAML 1.0
    title: T-Shirt Ordering Service
    version: 1.0.development
    baseUri: http://www.tshirt.com/api
  5. Go to the next line, and if necessary, click shelf-icon to expand the shelf. If you don’t see the shelf icon, refresh the page.

  6. Click the New Resource component on the shelf.

    This action adds lines of skeleton code at the cursor position. 

    new+resource

  7. Go to the next line, click New Resource a second time, go to the next line, and click New Resource a third time.

  8. Replace the text in the resource title and in its child element displayName, aligning the text as follows:

    
                
             
    1
    2
    3
    4
    5
    6
    
    /products:
      displayName: Products
    /orders:
      displayName: Orders
      /{orderId}/status:
        displayName: Status

    Here’s what the RAML looks like so far:

    
                
             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    
    #%RAML 1.0
    title: T-Shirt Ordering Service
    version: 1.0.development
    baseUri: http://www.tshirt.com/api
    /products:
      displayName: Products
    /orders:
      displayName: Orders
      /{orderId}/status:
        displayName: Status
  9. To the products resource, add a GET method: Go to the line below displayName:Products, and click GET on the shelf.

    methods

    Users of the API will be able to read information about products, but not post new products.

  10. To the /orders resource, add a POST method.

    Users will be able to place orders.

  11. To the status resource, add a GET method.

    Users will be able to check the status of an order.

  12. Add descriptions for each of the methods you add.

    
                
             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    
    #%RAML 1.0
    title: T-Shirt Ordering Service
    version: 1.0.development
    baseUri: http://www.tshirt.com/api
    /products:
      displayName: Products
      get:
        description: Get a list of all the inventory products
    /orders:
      displayName: Orders
      post:
        description: Place a new T-Shirt order
      /{orderId}/status:
        displayName: Status
        get:
          description: Get the status of an existing order
  13. Add the following code to match the t-shirt.raml file that you downloaded. Take care to tab to the correct level for each entry:

    • To ensure that POST requests sent to the /order resource are valid, add a schema to match against incoming requests.

    • Add an example message, to the post method of the /orders resource, placing it within body – application/json.

    • At the same level on the RAML hierarchy as the operation response label, add a queryParameters element to the GET operation with the following attributes:

      
                     
                  
      1
      2
      3
      4
      5
      
      queryParameters:
              email:
                description: Retrieve the status of an order with the same email that was used to place the order.
                pattern: ^[_a-z0-9-]+(\.[_a-z0-9-]+)*@[a-z0-9-]+(\.[a-z0-9-]+)*(\.[a-z]{2,4})$
                required: true

      The parameter makes it possible to query the status resource using the requester email.

Check your RAML code against the t-shirt.raml file that you downloaded, and proceed to simulate API calls.

Simulating API calls

To simulate the API, you call the API in the API console and check the responses. The RAML you downloaded specifies the following responses for the methods:

  • 200 (OK) response for all methods

  • 500 (server error) response for the POST order method in case something fails on the server side

  • 400 (client error) response for the GET status resource in case the user requests a nonexistent order

In the case of this API, the service behind the API generates the actual response that a user receives. The response example in the RAML is for previewing the response in API Console.

To simulate calls to the API and preview the responses:

  1. Above the API console on the right, turn on the Mocking Service.

    walkthrough-design-new-9cacb

    The baseUri has been commented out and replaced by a new URI.

  2. In the API console, click the GET tab for /products, and then click Try It.

  3. Repeat the last step for the other tabs, and enter these parameters on the status tab:

    • Order ID: 4321

    • Email: max@mail.com

      The call returns a status 200 and example responses provided in the RAML file.