Adding Examples to the API Spec

logo cloud IDE Cloud IDE

logo desktop IDE Desktop IDE

Add API fragments from Exchange for a data type and examples to the American Flights API specification. Then create your own examples for the specification, and add a custom message for a response.

Before You Begin

Complete all the procedures in Designing the American Flights API Spec.

Add Fragments from Exchange to Your Project

Add fragments to the project directory so that you can include them in your specification.

Training: American Flight Data Type fragment for an object that corresponds to the definition of a flight
Training: American Flights Example fragment for data that the API returns

To add the fragments:

In Anypoint Code Builder, open your American Flights API specification, american-flights-api.raml.
Open the Command Palette.
Show me how
- Use the keyboard shortcuts:
  
  Mac: Cmd+Shift+p
  
  Windows: Ctrl+Shift+p
- In the desktop IDE, select View > Command Palette.
- In the cloud IDE, click the (menu) icon, and select View > Command Palette.

Provide this command:

MuleSoft: Add fragment dependency from Exchange

If prompted, log in to Anypoint Platform so that you can download an asset.
In the Search for Asset field, provide the name of the data type asset to add:
```
Training: American Flight Data Type
```
Select the asset from the Assets From Exchange menu.
Select the latest version of the asset, such as v1.0.1.

The IDE adds the fragment as a dependency. When the process is complete, check for the AmericanFlightDataType.raml asset Project Dependencies area of the Explorer, for example:

The dependency is also listed in the exchange.json file for the project, in your project directory from the Explorer.

From the Command Palette, add another fragment:

MuleSoft: Add fragment dependency from Exchange

Provide the name of the asset to add:
```
Training: American Flights Example
```
Select the latest version of the American Flights Example asset.

The IDE adds the fragment as a dependency to Project Dependencies and exchange.json.
Proceed to Include the Fragments in the Specification.

Include the Fragments in the Specification

Use !include directives to add the fragments to the specification:

The AmericanFlight data type is defined in AmericanFlightDataType.raml.
The AmericanFlightsExample.raml example is for a 200 response to the get request.

To include the fragments:

Open american-flight-api.raml from the project directory in Explorer.

Replace the existing content with this:

#%RAML 1.0
title: American Flights API

types: (1)
  AmericanFlight: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flight-data-type/1.0.1/AmericanFlightDataType.raml

/flights:
  get:
    queryParameters:
      destination:
        required: false
        enum:
          - SFO
          - LAX
          - CLE
    responses:
      200:
        body:
          application/json:  (2)
            type: AmericanFlight[]
            examples: (3)
              output: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flights-example/1.0.1/AmericanFlightsExample.raml

  post:

  /{ID}:
    get:

1	Uses `!include` to add the `AmericanFlight` object from `AmericanFlightDataType.raml` as a data type Note that you can use built-in functionality to insert the `!include` directive and file path from the specification file, for example: After typing `AmericanFlight:` (with a space at the end), click Ctrl+Spacebar, start typing `!include`, and select `!include` from the drop-down menu in the RAML file, for example: Follow the same process to add the example, selecting `exchange_modules` directory and progressing step-by-step to `AmericanFlightsDataType.raml`, for example:
2	Sets the format of the body of the response to JSON (`application/json`) and configures the type of the response as an array of `AmericanFlight` objects (`AmericanFlight[]`)
3	Adds the `AmericanFlightsExample.raml` example

Proceed to Create and Include an Example for a Get Request by Flight ID.

Create and Include an Example for a Get Request by Flight ID

Create an example for the post response, and include it in the specification.

In the Explorer, right-click on an empty space, and create a folder named examples.
Right-click your examples folder, and create a new file named AmericanFlightExample.raml.

In the open file, add this example:

#%RAML 1.0 NamedExample
value:
    ID: 1
    code: ER38sd
    price: 400
    departureDate: 2017/07/26
    origin: CLE
    destination: SFO
    emptySeats: 0
    plane:
      type: Boeing 737
      totalSeats: 150

Return to your american-flights-api.raml file, and create a set of elements under /{ID}/get for responses:

#%RAML 1.0
title: American Flights API

types:
  AmericanFlight: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flight-data-type/1.0.1/AmericanFlightDataType.raml

/flights:
  get:
    queryParameters:
      destination:
        required: false
        enum:
          - SFO
          - LAX
          - CLE
    responses:
      200:
        body:
          application/json:
            type: AmericanFlight[]
  post:

  /{ID}:
    get:
      responses: (1)
        200:
          body: (2)
            application/json:
              type: AmericanFlight
              examples: (3)
                output: !include examples/AmericanFlightExample.raml

1	Adds a response with a `200` code
2	Specifies the JSON format and type (`AmericanFlight`) of the get request body
3	Adds your example from the `/examples` directory as the content for the body of the request

Proceed to Configure an Example for the Post Method.

Configure an Example for the Post Method

Define an example for the post request:

Specify that a request to the /flights:post method requires an object of the AmericanFlight type:

#%RAML 1.0
title: American Flights API

types:
  AmericanFlight: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flight-data-type/1.0.1/AmericanFlightDataType.raml

/flights:
  get:
    queryParameters:
      destination:
        required: false
        enum:
          - SFO
          - LAX
          - CLE
    responses:
      200:
        body:
          application/json:
            type: AmericanFlight[]
  post:
    body: (1)
      application/json:
        type: AmericanFlight (2)

  /{ID}:
    get:
      responses:
        200:
          body:
            application/json:
              type: AmericanFlight
              examples:
                output: !include examples/AmericanFlightExample.raml

1	Specifies a JSON-formatted body for the `post` method
2	Configures `AmericanFlight` as the type for the `post` method

Under your /examples folder, create a file named AmericanFlightNoIDExample.raml, and copy this example to the file:

#%RAML 1.0 NamedExample
value:
    code: ER38sd
    price: 400
    departureDate: 2017/07/26
    origin: CLE
    destination: SFO
    emptySeats: 0
    plane:
      type: Boeing 737
      totalSeats: 150

To simulate a new flight record, this example does not provide an ID parameter.

In the american-flights-api.raml file, add the example as a response to the post method, and include a custom message.

Notice the !include directive at number 5:

#%RAML 1.0
title: American Flights API

types:
    AmericanFlight: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flight-data-type/1.0.1/AmericanFlightDataType.raml

/flights:
  get:
    queryParameters: (1)
      destination:
        required: false
        enum:
          - SFO
          - LAX
          - CLE
    responses: (2)
      200:
        body:
          application/json:
            type: AmericanFlight[]
            examples:
              output: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flights-example/1.0.1/AmericanFlightsExample.raml

  post:
    body:
      application/json:
        type: AmericanFlight
        examples: (3)
          input: !include examples/AmericanFlightNoIDExample.raml
    responses:
      201:
        body:
          application/json: (4)
            example:
              message: Flight added (but not really)

  /{ID}:
    get:
      responses:
        200:
          body:
            application/json: (5)
              type: AmericanFlight
              examples:
                output: !include examples/AmericanFlightExample.raml

1	Select a destination.
2	Return an array of `AmericanFlight` objects for that destination.
3	Post an `AmericanFlight` object from an `examples/AmericanFlightNoIDExample.raml`.
4	Provide a custom message for a response in JSON format to the `post` method
5	Add your example from `examples/AmericanFlightExample.raml` as a response to the nested `get` request

Proceed to Testing the API Spec with the Mocking Service to test the API endpoints.