reuse::partial$beta-banner.adoc
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.
Complete all the procedures in tut-af-design-am-flights-api.adoc.
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
. partial$acb-reusable-steps.adoc -
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.
Use !include
directives to add the fragments to the specification:
-
The
AmericanFlight
data type is defined inAmericanFlightDataType.raml
. -
The
AmericanFlightsExample.raml
example is for a200
response to theget
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:
-
Uses
!include
to add theAmericanFlight
object fromAmericanFlightDataType.raml
as a data typeNote 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 toAmericanFlightsDataType.raml
, for example:
-
-
Sets the format of the body of the response to JSON (
application/json
) and configures the type of the response as an array ofAmericanFlight
objects (AmericanFlight[]
) -
Adds the
AmericanFlightsExample.raml
example
-
-
Proceed to 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 namedAmericanFlightExample.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
-
Adds a response with a
200
code -
Specifies the JSON format and type (
AmericanFlight
) of the get request body -
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.
Define an example for the post
request:
-
Specify that a request to the
/flights:post
method requires an object of theAmericanFlight
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
-
Specifies a JSON-formatted body for the
post
method -
Configures
AmericanFlight
as the type for thepost
method
-
-
Under your
/examples
folder, create a file namedAmericanFlightNoIDExample.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 thepost
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
-
Select a destination.
-
Return an array of
AmericanFlight
objects for that destination. -
Post an
AmericanFlight
object from anexamples/AmericanFlightNoIDExample.raml
. -
Provide a custom message for a response in JSON format to the
post
method -
Add your example from
examples/AmericanFlightExample.raml
as a response to the nestedget
request
-
-
Proceed to test-api-specification.adoc to test the API endpoints.