Design a New API

In this walkthrough, you create an API by writing a RAML file. You use the API Designer as your RAML editor.

This walkthrough requires API Creator permissions.

If you are using Studio 6, check our Quickstart for creating and designing a new API for a glimpse of Studio’s new features involved in this process.

About RAML

RAML (RESTful API Modeling Language) is a simple and practical language for describing APIs. RAML encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices. RAML is built on broadly-used standards such as YAML and JSON and is a non-proprietary, vendor-neutral open specification.

For more information, see:

• Documentation and Tutorials
• RAML Projects

RAML makes it easier for you to write your API, and provides a series of online tools that make it easier for developers to engage with your API.

A RAML file includes the following elements:

• Root
• Documentation
• Resources
• Methods
• Pattern-based, reusable elements

One of the key strengths of the RAML specification is the ability to reuse elements, which makes your API more succinct and more readable. However, the reusable elements in RAML are outside the scope of this walkthrough; for more information, visit the RAML tutorials.

The API Designer

While you may write your RAML file in any text editor, we recommend you check out the API Designer. Using the web-based API Designer, you can design an API quickly, efficiently, and consistently. API Designer consists of a RAML editor with an embedded RAML API console that proactively provides suggestions, error feedback, and a built-in, live testing environment.

A context-aware shelf at the bottom of the Designer displays a list of the components you can enter at that point in the hierarchy of your RAML. The components are arranged into categories that appear when relevant: Root, Docs, Parameters, Security, Resources, Methods, Traits and Types, Schemas, Body, and Responses.

Prerequisites

This walkthrough assumes that you followed steps in Create an API to log into Anypoint Platform and create an API version details page for the T-Shirt Service API.

Starting

You are now ready to start the walkthrough by opening your project in the API Designer.

1. Click the version number of your project. For example, 1.0.development.
   
2. Click Edit in API designer:
   
   The API Designer appears:
   

Design a New API in RAML

In this section, you design a RESTful, RAML-based API from scratch that 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 (mostly t-shirts)
• /orders (t-shirt orders, of course)
• orders each have a nested {orderId}/status, which is considered a sub-resource of orders.

You can type these resources into the RAML definition, or click components in API Designer to build the RAML definition. If you click to enter a component, it disappears from the shelf if it’s no longer available for entry. For example, if you select a GET method from the list of Methods, it disappears from the Shelf because you cannot have two GET methods on the same resource.

To design a new API in RAML:

1. In the new RAML file, notice that the information you provided when registering the new API (the name and version number) appears in the root.

   
   1
   2
   3
   
   #%RAML 0.8
   title: T-Shirt Ordering Service
   version: 1.0.development
   
   
   

2. On the next line, add a placeholder for a baseUri. Specify baseUri as: http://www.tshirt.com/api

   
   1
   2
   3
   4
   
   #%RAML 0.8
   title: T-Shirt Ordering Service
   version: 1.0.development
   baseUri: http://www.tshirt.com/api
   
   
   

   This placeholder helps you test the API and visualize what your final URL will look like with resources appended to it.
3. Go to the next line, and if necessary, click  to expand the shelf. If you don’t see the shelf icon, refresh the page.
4. Click the New Resource component on the shelf.
   This action adds lines of skeleton code at your cursor position. 
   
5. Go to the next line and click New Resource a second time.
6. Go to the next line and click New Resource a third time.
7. Replace the text in the resource title and in its child elements' displayName as follows:

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

8. Align the text as shown here.

   Elements that API Designer suggests in the shelf depend contextually upon where you place the cursor: the shelf allows placement only of elements that make sense in that particular position within the RAML tree structure.

   Here’s what your RAML should look like so far:

   
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   
   #%RAML 0.8
   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
   
   
   

   The API Console, displayed to the right of the editor, now contains information for Developers who want to know what resources are available on your API and how to access them.
   
9. To the products resource, add a GET method: Go to the line below displayName:Products, and click GET on the shelf.
   
   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 an order’s status.
12. Add valid descriptions for each of the methods you add.
    Note: You can copy and paste from this document to the API Designer to save time.

    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    
    #%RAML 0.8
    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
    
    
    

    In the API Console on the right, the resources have a corresponding method.
13. Click each method to read the descriptions you just added.
    
14. Use the responses component on the shelf to specify which responses will be valid for each of these 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 constructs the actual response that a user receives.  Nevertheless, it’s a good practice to provide a response example in the API RAML. With these examples in place, developers can then use the API Console to preview the structure of the response and build their consuming application accordingly.

      
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      45
      46
      47
      48
      49
      50
      51
      52
      53
      54
      55
      56
      57
      58
      59
      60
      61
      62
      63
      64
      65
      66
      67
      68
      
      #%RAML 0.8
      title: T-Shirt Ordering Service
      version: 1.0.development
      baseUri: http://www.tshirt.com/api
      /products:
        displayName: products
        get:
          description: Gets a list of all the inventory products
          responses:
            200:
              body:
                application/json:
                  example: |
                    [
                      {
                        "productCode": "TS",
                        "size": "S",
                        "description": "Small T-shirt",
                        "count": 30
                      },
                      {
                        "productCode": "TS",
                        "size": "M",
                        "description": "Medium T-shirt",
                        "count": 22
                      }
                    ]
           
      /orders:
        displayName: orders
        post:
          description: Places a new T-Shirt order
          responses:
            200:
              body:
                application/json:
                  example: |
                    {
                      "orderId": "4321"
                    }
            500:
              body:
                application/json:
                  example: |
                    {
                      "errorMessage": "The order couldn't be entered."
                    }
        /{orderId}/status:
          displayName: status
          get:
            description: Get the status of an existing order
            responses:
              200:
                body:
                  application/json:
                    example: |
                      {
                        "orderId": "4321",
                        "status": "Delivered",
                        "size": "M"
                      }
              400:
                body:
                  application/json:
                    example: |
                      {
                        "message": "The orderId doesn't match the specified e-mail"
                      }
      
      
      

15. To ensure that POST requests sent to the /order resource are valid, you can enforce that they all follow a given structure. You can provide a schema to match for incoming requests to ensure their validity. To help developers that are trying to understand what input your API requires, you can also add an example message, which is not only readable in the RAML code, but that is visible if the API is looked at in the API Console. Add both these elements into the post method of the /orders resource, placing them within body – application/json.

    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    
    /orders:
      post:
        description: Places a new T-Shirt order
        body:
          application/json:
            example: |
              {
                "size": "M",
                "email": "polly@mail.com",
                "name": "Polly Hedra",
                "address1": "77 Geary St.",
                "address2": "Apt 7",
                "city": "San Francisco",
                "stateOrProvince": "CA",
                "country": "US",
                "postalCode": "94131"
              }
            schema: |
              {
                "type": "object",
                "$schema": "http://json-schema.org/draft-03/schema",
                "id": "http://jsonschema.net",
                "required": true,
                "properties": {
                  "address1": {
                      "type": "string",
                      "id": "http://jsonschema.net/address1",
                      "required": true
                  },
                  "address2": {
                      "type": "string",
                      "id": "http://jsonschema.net/address2",
                      "required": true
                  },
                  "city": {
                      "type": "string",
                      "id": "http://jsonschema.net/city",
                      "required": true
                  },
                  "country": {
                      "type": "string",
                      "id": "http://jsonschema.net/country",
                      "required": true
                  },
                  "email": {
                      "type": "string",
                      "format": "email",
                      "id": "http://jsonschema.net/email",
                      "required": true
                  },
                  "name": {
                      "type": "string",
                      "id": "http://jsonschema.net/name",
                      "required": true
                  },
                  "size": {
                      "type": "string",
                      "enum": ["S", "M", "L", "XL", "XXL"],
                      "id": "http://jsonschema.net/size",
                      "required": true
                  },
                  "stateOrProvince": {
                      "type": "string",
                      "id": "http://jsonschema.net/stateOrProvince",
                      "required": true
                  },
                  "postalCode": {
                    "type": "string",
                    "id": "http://jsonschema.net/postalCode",
                    "required": true
                  }
                }
              }
    
    
    

16. At the same level on the tree structure as the operation’s 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
    
    
    

    This step makes it possible to query the status resource using the requester’s email.

Testing your RAML API in the Console

To test a user’s experience, call the API in the API console. 

1. Above the API console on the right, turn on the Mocking Service.
   
   Previously the baseUri was a placeholder for the duration of the design phase. The service isn’t actually tied to anything at the moment: calling http://www.tshirt.com/api doesn’t return a response. The Mocking Service provides the following response:
   
   The baseUri that you provided when declaring your basic information at the root has been commented out and replaced by a new URI. You’ve effectively published your API and it is now ready to receive live calls. You’ve also provided example responses. You can make live calls in the API Console or your browser, and the API returns data that you’ve provided in your RAML API definition. You can see what your API consumers see when they make calls to the API, and fully test APX. 
   Test that theory in the API console by making a GET request on the status of a particular order.
   
   As shown here, by providing a valid email address, the request URL reflects the resource path appended to thebaseUri just as it would with any functioning API. The call was performed live, and in response the user received a status 200: success! The response body is the example provided in the RAML file. In this case, the information isn’t important – it’s knowing how the response looks and that it’s successful that’s important.