Create an API Specification

For this project, let’s assume you’re building APIs for an ecommerce store. You begin by building a product API. One of the requirements for a product API is to provide details about a specific item in the store. You create a /products/{productId} endpoint that supports an HTTP GET method and provides details on what to request and how to respond.

Let’s start by going to Anypoint Platform’s Design Center. The Design Center is your cloud-based environment for building API specifications and Mule applications. For this project, we focus on API specifications.

1. If you’re not already logged in to Anypoint Platform, go to the Challenge section at the bottom of this page and click Launch.
2. After you’re logged in, scroll to Design Center and click Start designing.
   
3. Click Create+, then select New API Specification.
4. Enter QuickStart-Store in the Project name field.
5. Leave the default selection, I'm comfortable designing it on my own as is.
6. Click Create API.
   

In the top bar of the Design Center screen, ensure the QuickStart-Store/master branch is visible.

Next, a new API specification window in API Designer appears, which lets you create your API specification.

1. Delete the default text in the API Designer textbox so it’s empty.
2. Copy and paste the following RAML into the blank API Designer textbox.

#%RAML 1.0
title: DevRel-Quick Start Products API
version: v1.0
securitySchemes:
  basic:
    description: |
      This API supports Basic Authentication.
    type: Basic Authentication
securedBy: [basic]
types:
  product:
    properties:
      identifier?: string
      identifiers: IdentifierMap
      brand: string
      model: string
      rating: number
      description?: string
      pictures: string[]
      price: price
  price:
    properties:
      amount: amount
      salesUnit: salesUnit
  amount:
    properties:
      currency: string
      currencyValue: number
      name : string
  salesUnit:
    properties:
      code: string
      name: string
  Identifier:
    type: string
    pattern: ^[0-9A-Za-z-]+
    minLength: 3
    maxLength: 36
  IdentifierMap:
    type: array
    items:
      type: object
      properties:
        /[0-9A-Z-]+/:
          type: Identifier
/products:
  /{productId}:
      uriParameters:
        productId: string
      get:
        responses: 
          200:
            body:
              application/json:
                type: product
                example: |
                  {
                    "brand": "Anypoint",
                    "identifier": "eb8c8ca7-3c42-4489-a820-3aa138430b75",
                    "identifiers": [{
                      "SKU": "UGG-BB-PUR-06"
                    }],
                    "model": "Smart Slim Micro Stripe Shirt",
                    "rating": 5,
                    "description": "Shirt by ASOS Tall. Stripe woven fabric. Added stretch for comfort. Spread collar. Button placket. Slim fit - cut close to the body. Machine wash. 98% Cotton, 2% Elastane. Our model wears a size Medium Long and is 193cm/6'4\" tall",
                    "pictures": [
                      "https://launderkart.com/wp-content/uploads/2016/07/Shirt.jpg",
                      "https://cdni.llbean.net/is/image/wim/251423_47_41?wid=428&hei=494"
                    ],
                    "price": {
                      "amount": {
                        "currency": "USD",
                        "currencyValue": 34.90,
                        "name": "Amount"
                      },
                        "salesUnit": {
                        "code": "EA",
                        "name": "Each"
                      }
                    }
                  }
          404:
            body: 
              application/json:
                properties:
                  message: string
                example: |
                  {
                    "message" : "Product not found"
                  }

In the next step, you’ll test your API specification.

Understand the Specification

The specification you just entered starts by describing the overall API from the top level.

It then defines the authentication methods supported (basic auth) and assigns that globally for all endpoints and methods with the securedBy parameter.

The specification creates a data type of product with its parameters and types within it. Following that, you can find data types such as IdentifierMap, price, sales unit, and more. By specifying these data types, they can be reused by referencing them throughout the RAML file.

Scrolling further, the API specification describes the endpoint /products/{productId} and that it expects from the requester an item ID of type string. It also specifies its responses in JSON: A successful 200 response returns an instance of the product data type while a 404 Not Found exception response outputs a message property. Examples for both responses are also defined.