Anypoint Platform:

API Design
Student Manual

December 18, 2017

1
Table of Contents
INTRODUCING THE COURSE .................................................................................................... 4
Walkthrough: Set up your computer for class ..........................................................................5

PART 1: DESIGNING APIS .......................................................................................................... 7

MODULE 1: INTRODUCING RESTFUL API DESIGN ............................................................. 8
Walkthrough 1-1: Review and make a call to a SOAP API ......................................................9
Walkthrough 1-2: Review and make a call to an RPC API ....................................................13
Walkthrough 1-3: Review and make a call to a REST API ....................................................16

MODULE 2: TRANSLATING FUNCTIONAL REQUIREMENTS FOR APIS ..................... 18

Walkthrough 2-1: List the categories and actions for an API .................................................19
Walkthrough 2-2: Translate categories and actions into resources and methods .................21

MODULE 3: INTRODUCING API-LED CONNECTIVITY AND THE API LIFECYCLE ... 25

Walkthrough 3-1: Explore Anypoint Platform .........................................................................26

PART 2: DEFINING APIS WITH THE RESTFUL API MODELING

LANGUAGE (RAML) .................................................................................................................. 30

MODULE 4: DEFINING API RESOURCES AND METHODS .............................................. 31

Walkthrough 4-1: Create an API and define resources and methods in RAML 1.0 ...............32

MODULE 5: SPECIFYING RESPONSES................................................................................. 42

Walkthrough 5-1: Add HTTP 2xx responses to resource methods ........................................43
Walkthrough 5-2: Add responses bodies to return custom error information for
client-side errors.....................................................................................................................49
Walkthrough 5-3: Add response bodies to return custom error information for
server-side errors ...................................................................................................................53
Walkthrough 5-4: Add flexible content-type support to a resource method ...........................57
Walkthrough 5-5: Add caching information to HTTP responses ............................................62

MODULE 6: MODELLING DATA ............................................................................................ 64

Walkthrough 6-1: List datatypes and their attributes for an API .............................................65
Walkthrough 6-2: Create datatype fragments ........................................................................71
Walkthrough 6-3: Specify datatypes in resource methods .....................................................80
Walkthrough 6-4: Validate datatype attribute values using patterns ......................................85
Walkthrough 6-5: Define example fragments for datatypes ...................................................89

2
MODULE 7: DOCUMENTING AND TESTING APIS ............................................................ 97
Walkthrough 7-1: Add a documentation fragment to a RAML API definition .........................98
Walkthrough 7-2: Add description nodes to a RAML API definition .....................................104
Walkthrough 7-3: Use the mocking service in API console to test an API ...........................110

MODULE 8: MAKING APIS DISCOVERABLE .................................................................... 113

Walkthrough 8-1: Publish a RAML API fragment to Anypoint Exchange .............................114
Walkthrough 8-2: Publish a RAML API specification to Anypoint Exchange .......................119
Walkthrough 8-3: Add an API specification to the public portal ...........................................124
Walkthrough 8-4: Create a sample use case with API Notebook inside
the Exchange portal .............................................................................................................128

MODULE 9: REUSING PATTERNS ....................................................................................... 135

Walkthrough 9-1: Define and use a resource type for resources that perform
operations on a collection ....................................................................................................136
Walkthrough 9-2: Define and use a resource type for resources that perform
operations on a member ......................................................................................................141
Walkthrough 9-3: Define and use various traits for resources and methods .......................148

MODULE 10: MODULARIZING APIS ................................................................................... 154

Walkthrough 10-1: Create and use a library of traits............................................................155
Walkthrough 10-2: Internationalize documentation and resource description
using an overlay ...................................................................................................................161
Walkthrough 10-3: Define and use API extensions to promote portability to test
in multiple environments ......................................................................................................164

MODULE 11: SECURING APIS .............................................................................................. 170

Walkthrough 11-1: Define a custom security scheme for an API .........................................171
Walkthrough 11-2: Consume an OAuth2.0 security scheme for an API and secure
API resources.......................................................................................................................176

MODULE 12: ENHANCING API RESPONSES USING HYPERMEDIA .......................... 180

Walkthrough 12-1: Modify an API definition to implement state-specific client responses ..181

MODULE 13: VERSIONING APIS ......................................................................................... 186

Walkthrough 13-1: Add a new API version ..........................................................................187

3
Introducing the Course

Objectives:

• Learn about the course format.

• Download the course files.
• Make sure your computer is set up for class.
• Review the course outline.

4
Walkthrough: Set up your computer for class
In this walkthrough, you make sure your computer is set up correctly so you can complete the
class exercises. You will:

• Download the course files from the MuleSoft Training Learning Management System.

Download student files

1. In a web browser, navigate to http://training.mulesoft.com.
2. Click the My training account link.

3. Log in to your MuleSoft training account using the email that was used to register you for class.

Note: If you have never logged in before and do not have a password, click the Forgot your
password link, follow the instructions to obtain a password, and then log in.

4. On the My Learning page, locate the box for your class.

Note: If you do not see your event, locate the Current and Completed buttons under the My
Learning tab, click the Completed button, and look for your event here.

5
5. Click the event's View Details button.
6. Locate the list of course materials on the right-side of the page.

7. Click the student files link to download the files.

8. Click the student manual link to download the manual.
9. Click the student slides link to download the slides.
10. On your computer, locate the student files ZIP and expand it.
11. Open the course snippets.txt file.

Note: Keep this file open. You will copy and paste text from it during class.

6
PART 1: Designing APIs

Objectives:

• Describe REST API architecture.

• Describe API development lifecycle.
• Translate functional requirements for APIs into resources and HTTP methods.
• Navigate Anypoint Platform.

7
Module 1: Introducing RESTful
API Design

Objectives:

• Describe the common web API formats including SOAP, RPC and REST.
• Describe REST API architecture.
• List the rules for retaining REST principles in APIs.
• Describe design-first approach for REST APIs.

8
Walkthrough 1-1: Review and make a call to a SOAP API
In this walkthrough, you explore and understand a SOAP API. You will:
• Examine an example SOAP API.
• Make a call to a SOAP API endpoint to retrieve information.

Examine the Airline Information SOAP API

1. Return to the course snippets.txt file.
2. Copy the URL for the SOAP API: http://www.webservicex.net/new/Home/Index.
3. In a web browser, navigate to that URL
4. In the Webservices Directory, click Standards and Lookup Data.

9
 5. In the list of Webservices by category, click the Airport Information Webservice.

View the Airport Information Webservice endpoint WSDL

6. In the Airport Information Webservice Detail page, copy the link specified for the Endpoint.

7. In a new tab in the web browser, navigate to the Endpoint URL.

8. Locate the operations and HTTP methods supported by the webservice.

10
Make a call to retrieve data from an Airport Information Webservice operation
9. Go back to the Airport Information Webservice Detail page.
10. In the list of operations under Demo, click getAirportInformationByAirportCode.

11. In the Test parameter dialog box, type the airportCode parameter value as LHR.
12. Click Invoke.

13. Verify that a new tab opens that displays the response received from the SOAP webservice
operation.

14. Copy the content after the horizontal line in the response webpage.

11
15. Return to the course snippets.txt file and copy the URL for the Web Toolkit Online
http://www.webtoolkitonline.com/xml-formatter.html.
16. In a new tab in the web browser, navigate to that URL.
17. Paste the content in the XML Content area.
18. Click Format.

12
Walkthrough 1-2: Review and make a call to an RPC API
In this walkthrough, you explore an RPC API. You will:

• Examine the Slack RPC API.

• Make a call to an RPC endpoint.

Examine the Slack Web API

1. In a web browser, navigate to https://api.slack.com/web.

Note: This URL is also located in the course snippets.txt file.

2. Click the HTTP RPC style methods link in the middle of the page.

13
 3. Scroll down to the list of methods that describe the actions that can be performed with the
channels.
4. Click the channels.list method.

5. View the documentation for the channels.list method with the arguments and response
information.

Make a call to an endpoint

6. Scroll back up and click the Tester tab.

14
7. In the Tester, select the No token or Invalid token option for the token attribute and click the
Test Method button.

8. Verify that you see the response as not authorized or invalid authorization.

Note: To obtain a valid token, you need a Slack account and to belong to an organization with
channels and members. If you do have an account, you can generate tokens by following the
information in the link below the token attribute value in the tester.

15
Walkthrough 1-3: Review and make a call to a REST API
In this walkthrough, you explore a REST API. You will:

• Examine the Vimeo REST API.

• Make a call to a REST API endpoint to retrieve information.

Examine the Vimeo REST API

1. In a web browser navigate to https://developer.vimeo.com/api.

Note: This URL is also located in the course snippets.txt file.

16
2. In the left navigation bar, click Playground.
3. On the API/Playground page, click (Empty…) on the left-hand side.

4. In the expanded list of resources, click categories.

5. Click the Make Call button.
6. Verify the response has a status code 200.
7. Scroll the page and view the data for the Animation and Arts & Design categories.

17
Module 2: Translating Functional
Requirements for APIs

Objectives:

• Identify the different categories and actions for REST APIs.

• Convert categories to resources.
• Select HTTP methods to support the actions on categories.

18
Walkthrough 2-1: List the categories and actions for an API
In this walkthrough, you list out the functional requirements for an API. You will:

• Identify the categories for a REST API.

• Define actions for the categories to decide how users will consume the API.

Create user stories to define functional requirements for a banking API

1. Navigate to the APDevApiDesign3.9_studentFiles directory on your computer.
2. Navigate to module02 directory and open the WT2-1 User functionality text file in a text editor.

3. Read the file.

19
Brainstorm for categories and actions
4. Brainstorm with the class about possible categories and actions.

Note: The instructor may break you out into smaller groups to first brainstorm with some of your
peers.

List categories
5. In the WT 2-1 User functionality text file, add the following categories:

• CUSTOMERS
• ACCOUNTS
• TRANSACTIONS

List detailed actions

6. In the WT 2-1 User functionality text file, add a detailed list of actions that developers should be
able to perform with the API for each of the categories.
CUSTOMERS –
i. Get list of all customers in the bank
ii. Get customer information for a specific customer ID
iii. Register a new customer
iv. Update customer information for a specific customer ID
v. Delete a customer with a specific customer ID
ACCOUNTS –
vi. Get list of all accounts for a specific customer ID
vii. Get account information for a specific account ID
viii. Create a new account
ix. Update account information for a specific account ID
x. Delete account with a specific account ID

TRANSACTIONS –
xi. Get transactions for a specific account ID
xii. Get transaction information for a specific transaction ID

xiii. Create a new transaction

7. Save the file.

20
Walkthrough 2-2: Translate categories and actions into resources
and methods
In this walkthrough, you translate the categories and actions identified in the last walkthrough
into resources and methods. You will:

• Translate categories into resources.

• Identify HTTP methods for the actions.

Translate categories into resources

1. Return to the module02 directory in the studentFiles directory on your computer.
2. Open the WT2-2 Resources and methods file in a text editor.

3. Review the file.

21
Brainstorm about possible resources and methods
4. Brainstorm with the class about possible resources and methods.

Note: The instructor may break you out into smaller groups to first brainstorm with some of your
peers.

Specify resources
5. In the WT2-2 Resources and methods file, specify resources for the Customers entity.
• CUSTOMERS: Resource /customers
i. Get list of all customers - Resource /customers
ii. Register a new customer - Resource /customers
iii. Get customer information for a specific customer ID - Resource
/customers/{customer_id}
iv. Update customer information for a customer ID - Resource
/customers/{customer_id}
v. Delete a customer with a specific customer ID - Resource
/customers/{customer_id}

6. After a discussion, fill out the resources for Accounts entity.

• ACCOUNTS: Resource /accounts
i. Get list of all accounts for a specific customer ID – Resource
/customers/{customer_id}/accounts
ii. Create a new account – Resource /accounts
iii. Get account information for a specific account ID – Resource
/accounts/{account_id}
iv. Delete an account with a specific account ID – Resource
/accounts/{account_id}
v. Update account information for a specific account ID – Resource
/accounts/{account_id}

22
 7. Specify resources for the Transactions entity.
• TRANSACTIONS: Resource /transactions
i. Create a new transaction – Resource /transactions
ii. Get transactions for a specific account ID – Resource
/accounts/{account_id}/transactions
iii. Get transaction information for a specific transaction ID – Resource
/transactions/{transaction_id}

Specify HTTP methods for the actions

8. Specify methods for the identified resources.

• Get list of all customers – Method GET

• Register a new customer – Method POST
• Get customer information for a specific customer ID – Method GET
• Update customer information for a customer ID – Method PATCH
• Delete a customer with a specific customer ID – Method DELETE

• Get list of all accounts for a specific customer ID – Method GET

• Create a new account – Method POST
• Get account information for a specific account ID – Method GET
• Delete an account with a specific account ID – Method DELETE
• Update account information for a specific account ID – Method PUT

• Create a new transaction – Method POST

• Get transactions for a specific account ID – Method GET
• Get transaction information for a specific transaction ID – Method GET

23
Rearrange resources in the order of invocation
9. In the ACCOUNTS category, move the first line that contains the resource and method to get list
of accounts for a specific customer inside the CUSTOMERS category.

10. In the TRANSACTIONS category, move the second line that contains the resource and method
to get transactions for a specific account inside the ACCOUNTS category.

11. Save the text file.

24
Module 3: Introducing API-Led
Connectivity and the API Lifecycle

Objectives:

• Describe the API development lifecycle.

• Explain MuleSoft’s API-led connectivity approach.
• Describe the API development lifecycle with Anypoint Platform.
• Navigate Anypoint Platform.

25
Walkthrough 3-1: Explore Anypoint Platform
In this walkthrough, you get familiar with Anypoint Platform and its features. You will:

• Log in to Anypoint Platform.

• Explore the API entitlements in Anypoint Platform.

Log in to Anypoint Platform

1. In a web browser, navigate to https://anypoint.mulesoft.com.
2. Log in to Anypoint Platform.

Note: You can use a trial account or your company account (if you already have one). If you do
not have an account, sign up for a free, 30-day trial account now.

26
Explore Design Center in Anypoint Platform
3. In the Anypoint Platform homepage, click the top left menu icon.

Note: In the rest of the walkthroughs, we will refer to this menu icon as the main menu.

4. Click Design Center.

5. In the Design Center homepage, click Create in the top right corner.
6. Verify that you see the options to create API Specification, API Fragment and Mule application.

Note: In this class, we will be creating API Specification and API Fragment.

27
Explore Anypoint Exchange
7. In the main menu, select Exchange.

8. In the Exchange webpage, click the down arrow next to All types to the left of the search bar.
9. Click REST APIs.

28
10. Verify that you see all the public REST APIs listed.

29
PART 2: Defining APIs with the
RESTful API Modeling Language
(RAML)

Objectives:

• Create API definitions with RAML 1.0.

• Add documentation to RAML API definitions.
• Make APIs discoverable through Anypoint Exchange.
• Test APIs through the API console.
• Use patterns to refactor and modularize API definitions.
• Specify security schemes to secure resources in APIs.
• Add state specific responses to promote hypermedia.
• Learn when and how to version APIs.

30
Module 4: Defining API Resources
and Methods

Objectives:

• Use Anypoint Platform Design Center to create API definitions with RAML 1.0.
• Define resources and methods in RAML API definitions.

31
Walkthrough 4-1: Create an API and define resources and
methods in RAML 1.0
In this walkthrough, you create an API definition for the ACME Banking use case. You will:

• Create an API in Anypoint Platform Design Center.

• Define resources and nested resources identified for the API.
• Define HTTP methods for the resources.

Create a new API in Anypoint Platform Design Center

1. Return to Design Center in Anypoint Platform.
2. Click the Create button next to the search bar.

32
 3. In the New Project dialog box, enter the following information:

• Project Name: ACME Banking API

• Select the Start with API designer radio button

4. Click Create.

5. In the API designer page for ACME Banking API, go to the file browser section on the left, and
click acme-banking-api.raml.

Review the resources and nested resources identified for the API
6. Return to the WT 2-2 Resources and methods file in a text editor.

7. Review the resources.

33
Define the resources
8. Inside the RAML editor, place the cursor after the title node and add two new lines.
9. Add the /customers resource.

/customers:
10. Add two new lines and type the /accounts resource.
11. Similarly, add the /transactions resource.

12. In the API console on the right, verify that you can view the Resources section with the three
root level resources.

Define the nested resources

13. Add a new line below the /customers resource.
14. Indent by pressing the Tab key.
15. Add a nested resource called {customer_id}.

Note: Adding a curly parenthesis around the resource name indicates that the resource expects
a URI parameter with the value.

34
16. In a new line, indent and add a nested resource called accounts.

17. Add a new line after the main /accounts resource.

18. Indent and add a nested resource called {account_id}.
19. Add a nested resource called transactions.

20. Go to a new line after the main /transactions resource.

21. Indent and add a nested resource called {transaction_id}.

22. In the API console, go to the Resources section, click the arrow next to the /customers resource
to see the nested resources when you expand all the resources .

35
Review the get methods identified for the API
23. Return to the WT 2-2 Resources and methods text file.

24. Review the resources that have get methods.

Define HTTP methods for resources to retrieve collection and item data
25. Return to API designer.
26. Add a new line between the /customers and /{customer_id} resources.
27. Press tab to indent.

36
28. From the shelf, click get.

Note: Alternatively, you could select the keyword from the auto-complete drop-down box.

29. Delete the new line that is automatically added below the get method.
30. Similarly, add get methods to the nested /{customer_id} and /accounts resources.
31. Delete any extra empty lines.

32. In the API console, go to the Resources section.

37
 33. Click the arrow next to /{customer_id} nested resource; you should see the clickable labels to
the /{customer_id} get method.

34. Add get methods to the nested /{account_id} and /transactions resources.
35. For the /transactions resource, add a get method to the nested /{transaction_id} resource.

Review the methods identified for the /customers resource and nested resources
36. Return to the WT 2-2 Resources and methods file text file.

37. Review the methods for the /customers resource and its nested resources.

38
Define methods for the /customers resource to add, modify, and delete data
38. Return to API designer.
39. In the RAML editor, type or use the shelf to add a post method to the /customers resource.
40. Add patch and delete methods to the /{customer_id} nested resource.

41. In the API console, verify that you can view the added methods to the Resources section.

Review the methods identified for the /accounts resource and nested resources
42. Return to the WT 2-2 Resources and methods text file.

43. Review the methods for the /accounts resource and its nested resources.

39
Define methods for the /accounts resource to add, modify, and delete data
44. Return to API designer.
45. In the RAML editor, add a post method to the /accounts resource.
46. Add put and delete methods to the /{account_id} nested resource.

47. In the API console, verify that you can view the added methods in the Resources section.

Review the methods identified for the /transactions resource and nested
resources
48. Return to the WT 2-2 Resources and methods text file.

49. Review the methods for the /transactions resource and its nested resources.

Define methods for the /transactions resource to add, modify and delete data
50. Return to API designer.

40
51. In the /transactions resource, add a post method.

52. In the API console, verify that you see the added methods in the Resources section.

41
Module 5: Specifying Responses

Objectives:

• Create HTTP method responses.

• Use status codes in HTTP responses.
• Add error handling and caching information to HTTP responses.
• Select and specify the types of content returned in HTTP responses.

42
Walkthrough 5-1: Add HTTP 2xx responses to resource methods
In this walkthrough, you add HTTP 2xx response bodies to all resource methods. You will:

• Define media type for the API resource methods.

• Add a HTTP 200 response body to all GET and DELETE methods indicating success of
the HTTP request.
• Add a HTTP 201 response body to all POST methods.
• Add a response body with both HTTP 200 and 201 status codes to the PUT method.
• Add a HTTP 204 response body to PATCH methods.

Add a mediaType node to indicate the request and response body type
1. Return to API designer.
2. Add a new line after the title node at the root. beginning of the RAML definition.

43
 3. From the shelf, add the mediaType node.

4. Add a space after the colon in the mediaType node.

5. From the shelf, click application/json.

Add a HTTP 200 response body to GET methods indicating request success
6. Go to the customers get method, and add a new line below it.
7. Press the tab key to indent.

44
 8. From the shelf, add the responses node.

9. In the new line, add a HTTP status code 200 node.

10. Add a body node inside the HTTP 200 response.
11. Copy the lines from responses node till the body node.
12. Paste the copied lines in the get methods of the following resources:

• /customers/{customer_id}
• /customers/{customer_id}/accounts
• /accounts/{account_id}
• /accounts/{account_id}/transactions
• /transactions/{transaction_id}

Note: If the indentation of the lines change, fix them before moving on to the rest of the resource
methods. Often times RAML errors are due to indentation issues. If your RAML contains errors
you can view them in the API console.

Add a HTTP 200 response body to the DELETE methods indicating request
success
13. Similarly, paste the copied lines inside the delete methods of the following resources:

• /customers/{customer_id}
• /accounts/{account_id}

Add a request body to all POST methods

14. In the RAML editor, go to the /customers post method and add a new line.

45
 15. Press the tab key to indent.
16. Add a body node.
17. Similarly, add the request body for the post methods of the following main resources:

• /accounts
• /transactions

Add a HTTP 201 response body to POST methods indicating request success
18. Add a HTTP 201 response body to the post method of the /customers resource.
19. Add a new line above the 201-response body and indent to the same level.
20. In the shelf, click headers.

21. In the shelf, scroll and click the Location header.

22. Delete the new line created below the Location line.

Add a request body and a HTTP 200 and 201 response body for the PUT method
23. In the /{account_id} put method, add a request body.

46
 24. Below the request body, add a HTTP 200 response body.

25. Add a 201 status code to the response, with a Location header in passed in the response.

Add an HTTP 204 response body to PATCH methods indicating request success
26. In the /{customer_id} patch method, add a request body.

27. Add a new line after the patch request body, and indent to the same level as the body node.
28. In the shelf below, click responses.
29. In the shelf, click 204.
30. Delete the new line created below the HTTP status code 204 line.

View the API console

31. In the API console, under the Resources section, locate the /accounts/{account_id} resource.
32. Click PUT.

47
33. Locate the two HTTP status code responses under Response.

34. Click the back arrow to go back to the list of Resources.

48
Walkthrough 5-2: Add responses bodies to return custom error
information for client-side errors
In this walkthrough, you add response bodies to return a custom error information objects for
client-side errors. You will:

• Add HTTP 4xx status code responses to all GET and DELETE methods.
• Create a custom error information object to be returned in the response body.

Add a 404 Not Found HTTP status code response to a GET method
1. Return to API designer.
2. In the /customers resource get method, add a new line after HTTP 200 response body.
3. Go back a tab space, so the cursor is at the same indent level as the 200.
4. Type 4, then scroll through the shelf to locate 404 and click it.

49
 5. In the shelf, click body.

Create a custom object to display an error message for the response

6. In the new line, type:

properties:
7. Press enter and press tab to indent the line of code.
8. In the new line below properties, type:

statusCode:
9. Press spacebar, and scroll down in the shelf and click string.

10. Press enter and type:

message: string

50
Add the HTTP 404 response body to all GET and DELETE methods
11. Copy the HTTP 404 response body lines.

12. Add the HTTP 404 response body to the get methods of the following resources:

• /customers/{customer_id}
• /accounts
• /accounts/{account_id}
• /accounts/{account_id}/transactions
• /transactions/{transaction_id}

Note: Make sure to fix the indentation after pasting these lines under the resource method.

13. Add the 404-response body to the delete methods of the following resources:

• /customers/{customer_id}
• /accounts/{account_id}

View the API console

14. In the API console, under the Resources section, click the GET for the /customers resource.

51
15. In the Response section click the 404 tab; you should see the custom error message properties
listed under the application/json object.

16. In the API console, click the back arrow to go back to the list of resources.

52
Walkthrough 5-3: Add response bodies to return custom error
information for server-side errors
In this walkthrough, you add response bodies to return error status codes and error messages
for server-side errors. You will:

• Add HTTP 5xx status code responses to all PATCH, PUT and POST methods.
• Create a custom error message object to be returned in the response body.

Add a 501 Not Implemented HTTP status code response to the PATCH method
1. Return to API designer.
2. In the /customers resource patch method, add a new line under HTTP 204 status code.
3. Type 5, then scroll through the shelf to locate 501 and click it.

4. In the shelf, click body.

53
Create a custom object to display an error message for the response
5. In the new line, type:

properties:
6. In the new line below properties, type:

statusCode:
7. Press spacebar and scroll down in the shelf and click string.

8. Press enter and type:

message: string

Add the HTTP 501 response body to the PUT method

9. Copy the HTTP 501 response body lines.
10. Go to the the /accounts/{account_id} put method, and paste the 501 response body lines.

54
Add the 503 Service Unavailable HTTP status code response to a POST method
11. In the /customers resource post method, add a new line under HTTP 201 response body.
12. Go back one tab space, so the cursor is at the same indent level as 201.
13. Type 5, then click 503 in the shelf.

14. In the shelf, click body.

15. In the new line, type:

properties:

16. Add a new line, indent one level further and type:

statusCode:
17. Add a space after the colon, and scroll down to the shelf.
18. Select the string type.
19. Add a new line and type:

message: string

55
Add the HTTP 503 response body to all POST methods
20. Copy the HTTP 503 response body lines.
21. Paste the HTTP 503 response body lines to the post methods of the following resources:

• /accounts
• /transactions

View the API console

22. In the API console, under the /customers resource, click the POST method.
23. Scroll down to the Response section and click the 503 tab; you should see the custom error
message properties listed under the application/json object.

24. In the API console, click the back arrow to go back to the list of resources.

56
Walkthrough 5-4: Add flexible content-type support to a resource
method
In this walkthrough, you add flexible content-type to HTTP response of a resource method.
You will:

• Add XML body type to the HTTP 200 response of a resource method.
• Add an optional accept header to the request to specify the type of response accepted
by the client.
• Add a relevant HTTP status code for client-side error when an unsupported type is
requested.

Add XML response media type to the HTTP 200 responses body for /customers
GET method
1. Return to API designer.
2. In the /customers resource get method, add a new line below the HTTP 200 response body.
3. Press tab and in the shelf, click application/json.
4. In the new line, go back one-tab space.
5. In the shelf, click application/xml.
6. Delete the new line created below application/xml.

57
View the API console
7. In the API console, under the /customers resource, click the GET method.

8. Scroll down to the Response section.

9. In the HTTP 200 response body type, click the drop-down menu next to application/json; you
should see both application/json and application/xml listed as possible return types.

Add an optional accept header to specify the media type of response body
accepted by the client
10. In the editor, go to the /customers resource get method.
11. Add a new line below get.

58
 12. Press tab in the new line.
13. In the shelf, click headers.

14. In the shelf, click Accept.

15. Delete the new line created below the Accept header property.
16. Go to the line with the Accept header, and add a ? between Accept and the colon to change it to
an optional parameter.

Note: When you make the Accept header optional, the API can be implemented to return the
response body in JSON by default when the header is not specified. It also indicates that the
client accepts all media type responses.

View the API console

17. In the API console, under the Resources section, go to the /customers resource, click GET.

59
 18. In the Headers section for the request, locate the Accept header.

Add a HTTP 406 response to the resource method to indicate error when an
unsupported type is requested
19. In the /customers resource, add a new line below the message property in the HTTP 404
response body.
20. Press backspace or delete three times to go three tab spaces back.
21. Type:

406:

22. Press enter and press tab.

23. In the shelf, click body.
24. In the new line type:

properties:
25. Add a new line and indent one level further.
26. In the new line, add a property called statusCode of type string.
27. Press enter.
28. In the new line, add a property called message of type string.

60
View the API console
29. In API console, under the Resources section, go to the /customers resource, click GET.
30. In the Response section, click the 406 tab to view the HTTP 406 response body.

31. Go back to the list of resources by clicking the back arrow.

61
Walkthrough 5-5: Add caching information to HTTP responses
In this walkthrough, you indicate that a resource is cacheable by using cache-control headers.
You will:

• Add a Cache-Control header to a GET response to enable caching.

• Add an Expires header to a GET response to set the date when the cached resource
becomes invalid.

Add a Cache-Control header to a GET response to enable caching

1. Return to API designer.
2. In the /customers resource get method, add a new line below the line with HTTP 200 node.
3. Press tab, and in the shelf, click headers.

4. In the shelf, click Cache-Control.

62
Add an Expires headers to a GET response to set the date when the cached
resource becomes invalid
5. In the RAML editor, go to the new line after the Cache-Control header.
6. In the new line, align the cursor at the same indent level as the previous line.

7. In the shelf, click Expires.

8. In the shelf, click type.

9. In the shelf, scroll down and click datetime.

View the API console

10. In the API console, under the Resources section, go to the /customers resource, click GET.
11. In the Response section, locate the Expires and Cache-Control headers in the HTTP Status 200
response.
12. In the API console, click the back arrow to go to the list of resources.

63
Module 6: Modelling Data

Objectives:

• List datatypes and their attributes to be returned from or sent to resource methods.
• Create datatype fragments.
• Set request and response body types to datatypes.
• Create examples for datatype fragments.
• Include examples in datatype fragments.

64
Walkthrough 6-1: List datatypes and their attributes for an API
In this walkthrough, you identify datatypes and their attributes to be used in HTTP request and
response bodies for the ACME Banking API. You will:

• List the datatypes required for the resource methods.

• Identify the attributes for each datatype.
• Create necessary additional datatypes to simplify the identified datatypes.
• Identify optional attributes in datatypes.

List out the base datatypes required for the resource methods
1. On your computer, navigate to the studentFiles folder.
2. Navigate to the module06 directory and open the WT6-1 Datatypes and attributes text file in a
text editor.

65
Identify the attributes for each datatype
3. Brainstorm with the class about possible attributes for each datatype.

Note: The instructor may break you out into smaller groups to first brainstorm with some of your
peers.

4. After a brief discussion, type the following attributes and their types for the Customer datatype:

• customerID type: string

• prefix type: string
• firstName type: string
• middleName type: string
• lastName type: string
• suffix type: string
• displayName type: string
• addressLine1 type: string
• addressLine2 type: string
• city type: string
• state type: string
• country type: string
• zipCode type: string
• phone type: string
• email type: string
• ssn type: string
• dateOfBirth type: date-only

66
5. After a brief discussion, type the following attributes and their types for the Account datatype:

• accountID type: string

• accountType type: enum [Checking, Savings, Overdraft Savings, Credit Card]
• accountNumber type: string
• accountOwner type: Customer[]
• accountBalance type: Money (since it should include currency and an amount)
• IBAN type: string
• bankCode type: string
• routingNumber type: string
• bankName type: string
• swiftBIC type: string
• interestRate type: number
• createdAt type: datetime
• modifiedAt type: datetime

6. After a brief discussion, type the following attributes and their types for the Transaction datatype:

• transactionID type: string

• fromAccount type: Account
• toAccount type: Account
• transactionType type: enum [atm, check, deposit, cashWithdrawal, online, sepa]
• transactionName type: string
• transactionAmount type: Money
• newAccountBalance type: Money
• postedAt type: datetime
• completedAt type: datetime

67
Create necessary additional user-defined datatypes as per the attribute definition
7. In the Customer datatype, select attributes from addressLine1 to zipCode and cut the lines and
paste them at the end of the document.

8. In the empty line, in between the Customer datatype attributes, type:

• address type: Address

9. For the attributes that were to the end of the document, add a header to indicate them as
attributes for Address datatype.

10. Similarly, create a new datatype Money with the following attributes:

• currency type: string

• amount type: string

68
 11. In the Account datatype, go to the line that contains the accountOwner attribute and change the
type to AccountOwner[].

Note: Although using Customer data type for accountOwner attribute is valid, we create an
AccountOwner datatype because you only need a subset of information (name, ID and ssn)
about the customer to add them as an account owner. This way the entire customer datatype
and their attributes are not necessary.

12. Create a new datatype AccountOwner with the following attributes:

• customerID type: string

• ssn type: string
• displayName type: string

13. In the Account datatype, select the attributes bankCode, bankName and swiftBIC and move
them to end of the document and name them as attributes for Bank datatype.

14. Reference the bank datatype within the Account datatype as:

• bank type: Bank.

Identify optional attributes in the datatypes

15. Brainstorm with the class about the attributes that could be optional for each datatype.

69
16. Identify the optional attributes and add a ? right after the attribute name.

70
Walkthrough 6-2: Create datatype fragments
In this walkthrough, you define datatype fragments for the identified datatypes for the ACME
Banking API. You will:

• Create datatype fragment files for the identified datatypes.

• Define the datatypes with required and optional attributes.
• Include the datatype fragments in the main RAML API definition.

Refactor the custom error message object to use a datatype

1. Return to API designer.
2. In the file browser, click the + icon in the Files header section.
3. In the drop-down menu, click New folder.

4. In the Add new folder dialog box, set the name to datatypes.

71
5. Click Create.
6. In the file browser, click acme-banking-api.raml.
7. Go to the /customers resource get method HTTP 404 response body and copy the lines that
define the properties of the custom error message.

8. In the file browser, hover the mouse pointer along the datatypes folder; you should see an +
icon and a menu icon to the right of the folder name.
9. Click the + icon and click New file from the drop-down menu.

10. In the Add new file dialog box, click the name drop-down menu next to Specification textbox.
11. Scroll down and click Data Type.

12. Rename the file as CustomErrorMessage.raml.

72
 13. Click Create.
14. Go to the end of the first line in the CustomErrorMessage file and press enter.
15. Type the following:

type: object
16. Press enter and paste the copied lines below.

17. Select the statusCode and message properties line, and press Shift+Tab to indent the lines
properly.

Create a Customer datatype fragment

18. In the file browser, click the + icon next to the datatypes folder and click New file.
19. In the Add new file dialog box, set the value of the field which reads Specification to Data Type.
20. Rename the file as Customer.raml.

21. Click Create.

22. In the RAML editor, go to the end of the first line and press enter to add a new line.

73
23. In the new line add the type node with the value object.

24. In the shelf, click properties.

25. On your computer, return to the WT 6-1 Datatypes and attributes text file.
26. Return to API designer.
27. Add the attributes for the Customer one below the other; for each, specify the attribute name,
followed by a colon, and then the attribute type.
28. For the address property type the value as:

address: !include Address.raml

Note: We will be importing the Address datatype fragment file later in this walkthrough.

29. Add a ? after the prefix and suffix attribute names to specify them as optional attributes.

74
Create an Account datatype fragment
30. Similarly, add another new type file and set its name to Account.raml.

31. In the RAML editor, add ? for the attributes that need to be set as optional for the Account
datatype.

• Use the enum datatype to specify the accountType that has possible values of Checking,
Savings, Overdraft Savings, Credit Card.

Note: The enum datatype should be defined in a line below the attribute as a key-value pair.

75
Create a Transaction datatype fragment
32. Similarly, create another new Type file called Transaction.raml and type the required and
optional attributes for the Transaction datatype.
33. Use the enum datatype to specify the transactionType has possible values of atm, deposit,
cashWithdrawal, sepa, and online.

Import other datatype fragment files into API Designer

34. In the file browser, click the menu icon on the top right next to the + icon in the Files menu bar.

35. Click Import.

76
 36. In the Import file dialog box, click the Choose File button.

37. In the file chooser, locate the studentFiles directory, open the module06 folder, and double- click
Address.raml.
38. Click Import.
39. In the left-side navigation, click Address.raml and drag-and-drop it inside the datatypes folder.
40. Similarly, import Money.raml, AccountOwner.raml and Bank.raml and drag them into the
datatypes directory.
41. Verify the project structure has the datatype files inside the datatypes folder, and the acme-
banking-api.raml file in the root location.

Include the datatype fragments in the main RAML API definition

42. In the file browser, select acme-banking-api.raml.
43. In the RAML editor, go to the end of the line that contains the mediaType node and add two new
lines below it.
44. Go to the second new line and in the shelf, click types.

77
 45. In the new line type,

Customer: !i
Note: Make sure there is a space between the colon after Customer and the !.

46. In the shelf, click include.

47. Press spacebar and in the shelf, click datatypes.
48. Type / and in the shelf, click Customer.raml.

49. Similarly, include the Account, Transaction and CustomErrorMessage datatypes in the acme-
banking-api.raml file.

View the API console

50. In the API console, click the arrow in the Types section to expand it.

78
51. Verify that you see the following datatypes listed:

52. Click the Customer datatype to view its properties.

79
Walkthrough 6-3: Specify datatypes in resource methods
In this walkthrough, you specify the type of data to be sent in the request or received from the
response of a resource method. You will:

• Add the type parameter with a reference to the datatype for all resource method
response bodies.

Add type parameters for the appropriate method requests and responses
1. Return to acme-banking-api.raml in API designer.
2. In the /customers resource get method, go to the HTTP 200 response body, and add a new line
below the response body type application/json.
3. Press tab and in the shelf, click type.

80
4. In the shelf, click Customer and add [] (square brackets); to denote an array of Customer
objects as the response body.

5. Copy the line type: Customer[] and go to the end of the next line that contains the
application/xml response body type.
6. Press enter and press tab.
7. Paste the copied line.

8. Similarly, in the /accounts and /transactions nested resource get methods, add the respective
Account and Transaction array datatypes to the HTTP 200 response body.

9. In the /customers resource post method, add a new line below the request body media type.

81
10. Press tab and type:

type: Customer

11. Add the request body for the /accounts post method, and the /transactions post method with the
respective datatypes in the request.

12. Go to the /{customer_id} get method.

13. Add the HTTP 200 response body type as Customer.

type: Customer

14. In the /{account_id} and /{transaction_id} get methods, add the type node to the HTTP 200
response bodies, with the value set to their respective datatypes.

82
 17. In the /{account_id} put method, add the type node for request body with the value as Account.

View the API console

15. In the API console, under the Resources section, go to the /accounts/{account_id} resource,
click GET.
16. Verify that you can see the Account object listed in the 200 Response section of the resource.

Reference the custom error message datatype in the necessary resource method
responses
17. In the RAML editor, go to the /customers resource get method HTTP 404 response body and
delete the lines that contain the custom error object properties.

83
18. Set the datatype to CustomErrorMessage.

type: CustomErrorMessage

19. Modify all the other error response bodies in the RAML definition to be of this datatype.

84
Walkthrough 6-4: Validate datatype attribute values using
patterns
In this walkthrough, you add patterns and format values to validate necessary datatype
attributes. You will:

• Specify attribute patterns and format values for certain datatype attributes.

Specify attribute patterns and format values for necessary datatype attributes
1. Return to API designer.
2. In the file browser, expand the datatypes folder and select Account.raml.
3. Go to the line that contains the IBAN attribute and delete the type string from the line.
4. Press enter and press tab.

5. Type:

type: string
Note: Make sure you add a space between the colon after type and the value string. Splitting
the original line this way allows you to add additional properties to the string attribute.

85
6. In the shelf, click pattern.

7. Return to or open the course snippets.txt file.

8. Locate the Module 6 section and copy the pattern for IBAN.
9. Return to API designer and paste the text in the value of the pattern node.

10. Go to the line that contains the interestRate attribute and delete number from the value.
11. In a new line, set the interestRate attribute to:

type: number
12. In the shelf, click format and specify the format value as double.

13. In the file browser section, click Money.raml.

14. In the currency attribute, delete the string type from the line.
15. In a new line, set the currency attribute to:

type: string
16. Add a new line below the currency type node line.

86
17. In the shelf, click pattern.

18. Return to the course snippets.txt file and copy the pattern value for currency and paste it in the
RAML editor.

19. In the amount attribute, delete the string type from the line.
20. In a new line, set the amount attribute to:

type: string
21. Add a new line below the amount type node line.
22. In the shelf, click pattern.
23. Return to the course snippets.txt file and copy the line that contains the pattern value for amount
and paste it in the RAML editor.

87
View the API console
24. In the file browser, click acme-banking-api.raml.
25. In the API console, expand the Types section and click the Account datatype.
26. Click the Account datatype and scroll down to the Properties section.
27. Verify that you can view the patterns enforced for the accountBalance currency and amount
properties.

28. In the API console, click the back arrow to go back to the list of datatypes and resources.

88
Walkthrough 6-5: Define example fragments for datatypes
In this walkthrough, you create example fragments for each of the datatypes. You will:

• Create example fragments for the datatypes.

• Include examples in datatype fragments.

Create example fragment for the Customer datatype

1. Return to API designer.
2. In the file browser section, click the + icon next to the Files section header and select New
folder.
3. In the Add a new folder dialog box, set the name of the folder to examples.

89
4. Click Create.
5. In the file browser, hover over the examples folder, and click the + icon.
6. In the drop-down menu, select New file.
7. In the Add new file dialog box, click the drop-down arrow next to the field that contains the value
Specification and select Example.

8. Set the name to CustomerExample.raml and click Create.

9. In the CustomerExample.raml file, add a new line below the value node and press tab.
10. Return to the course snippets.txt file and copy the snippet for the CustomerExample.raml
content values and paste it in the new line.

Note: Fix the indentation to make sure all the attributes are one-tab level inside the value node.

90
Create example fragment for the Account datatype
11. Create a new example file AccountExample.raml and copy the example data from the course
snippets.txt file.

Create example fragment for the Transaction datatype

12. Create a new example file called TransactionExample.raml and copy the example data from the
course snippets.txt file.

91
Include example fragments in the datatype fragments
13. In the file browser section, go to datatypes/Customer.raml.
14. In the Customer datatype, add a new line at the end of the file.
15. Go back one-tab space and type:

example: !include examples/CustomerExample.raml

16. Similarly, include the AccountExample.raml example in Account.raml datatype.

17. Similarly, add the TransactionExample.raml example in Transaction.raml datatype.

18. In the file browser, click acme-banking-api.raml.

92
View the API console
19. In the API console, go to the list of resources, under the /{transaction_id} resource, expand the
list of methods and click GET.

20. In the Response section, click the Examples tab and verify that you see the
TransactionExample.

21. Click the back arrow to go back to the list of resources.

Include multiple examples in the datatype fragments

22. In the file browser, click the menu icon next to Files header.

93
23. Click Import.

20. On your computer, go to the studentFiles > module06 directory.

21. Select the CustomerExample1.raml.
22. Make sure you move the imported example file into the examples folder (if it is not already
imported there).
23. Similarly, import the CustomerExample2.raml example fragment.

24. In the file browser, open the datatypes > Customer.raml fragment.
25. Add a new line at the end and type:

examples:
26. Add a new line and indent one level in and type the following:

example1: !include ../examples/CustomerExample1.raml

94
 27. Add another line below example1 and include CustomerExample2.raml as example2.

View the API console

28. In the file browser, click acme-banking-api.raml.
29. In the API console, expand the Types section, and click Customer.

30. Click the Examples tab for the Customer datatype.

95
31. Verify that you see three examples listed for the datatype.

96
Module 7: Documenting and
Testing APIs

Objectives:

• Add documentation and description nodes to a RAML definitions.

• Use the mocking service to create API endpoints.
• Use the API console to test API endpoints.

97
Walkthrough 7-1: Add a documentation fragment to a RAML API
definition
In this walkthrough, you add documentation for the ACME Banking API RAML definition. You
will:

• Create a documentation fragment.

• Link the documentation fragment to the main RAML definition file.
• Link multiple documentation fragments to the documentation node in the RAML API
definition.

Create a documentation fragment and link it to the main RAML definition file
1. Return to API designer.
2. In the file browser, click the + icon next to the Files header.
3. Select New folder.

4. In the Add new folder dialog box, set the folder name to documentation.

98
5. Click Create.
6. In the file browser section, click the + icon next to the documentation folder and select New file.
7. In the Add new file dialog box, click the drop-down arrow next to the Specification field.
8. Scroll down and select User Documentation.
9. Set the file name to acmeBankDoc.raml.
10. Click Create.
11. In the RAML editor, set the title property to ACME Banking API Home.

Note: Be sure to add a space after the colon.

12. Add a space after the colon in the content node line and type a | (the pipe operator).

Note: The pipe operator indicates the value of the node is a multi-line input.

13. Return to the course snippets.txt file.

14. Locate Module 7 and copy the text under Snippet #1.

15. Return to API designer.

32. In acmeBankDoc.raml, press enter after the pipe operator in the content node line.
16. Press tab and paste the copied lines.

17. Return to the course snippets.txt file and copy Snippet #2.

99
 18. Return to API designer and add two new lines after the first snippet documentation.
19. Paste the copied text in the second new line.

Link the documentation fragment to the main RAML definition file

20. In the file browser, click acme-banking-api.raml.
21. Add a new line before the types node at the root.
22. In the shelf, click documentation.

23. In the new line created below the documentation node, type the following:

- !include
Note: Be sure to put a space between the - and the !.

24. In the shelf, click documentation.

33. After the word documentation word, type /.
34. In the shelf, click acmeBankDoc.raml.

100
 25. Add a new line.

View the API console

26. In the API console, locate the Documentation section and click ACME Banking API Home.

27. Verify that you can view the ACME Banking API Home content.

Create another documentation fragment

28. In the file browser, click the + icon next to the documentation folder and select New file.
29. In the Add new file dialog box, click the drop-down arrow next to the Specification field and
select User Documentation.
35. Set the file name to acmeBankHeadline.raml.
30. Click Create.
31. In the editor, set the type node value to ACME Bank Headline.

101
 32. In the line that contains the content node, press spacebar after the colon and type | (pipe
operator)

33. Return to the course snippets.txt file and copy Snippet #3.

34. Return to API designer, add a new line and indent one level further.
35. Paste the copied lines.

Link the documentation fragment to the main RAML definition file

36. In the file browser, click acme-banking-api.raml.
37. Add a new line below the documentation node definition.
38. Press tab and add an include statement to add the acmeBankHeadline.raml file:

- !include documentation/acmeBankHeadline.raml

102
View the API console
39. In the API console, under the Documentation section, click ACME Bank Headline.

40. View the documentation content.

41. Click the back arrow, to go back to the page with the list of documentation, types, and
resources.

103
Walkthrough 7-2: Add description nodes to a RAML API definition
In this walkthrough, you add documentation for the ACME Banking API RAML definition. You
will:

• Add descriptions to resource methods.

• Add displayName to resource methods.
• Add descriptions to URI parameters.
• Add description and example nodes to request and response headers.

Add a description to a get method

1. Return to API designer.
2. In the /customers resource, create a new line below the line that contains the get method.
3. Press tab and in the shelf, click description.

104
 4. Set the description node value to:

Retrieve a list of customers

Add descriptions to other methods

5. Add some or all the following descriptions to the specified methods for the following resources:

• /customers post Add a new customer

• /customers /{customer_id} get Retrieve a customer with a specific customer ID
• /customers /{customer_id} patch Update a specific customer info
• /customers /{customer_id} delete Delete a specific customer

Add displayName nodes to resource methods

6. In the /customers resource, add a new line below the get method description.
7. In the shelf, click displayName.
8. Type the value of the displayName node as:

Get all customers

Note: The displayName node helps in better readability of the API functionality in the REST
Connect functionality in Flow Designer.

9. Similarly add some or all the following displayName nodes to the following resource methods:

• /customers post Add new customer

• /customers /{customer_id} get Get a customer by customer ID
• /customers /{customer_id} patch Update a customer by customer ID
• /customers /{customer_id} delete Delete a customer by customer ID

105
View the API console
10. In the API console, under the Resource section, locate the /{customer_id} nested resource and
expand it to view the methods.
11. Click GET.

12. View the Description above the Request section of the GET method.

Add description and example nodes to a method's request and response headers
13. In the /customers resource, locate the optional Accept header and add a new line below it.
14. Press tab in the new line and add a description with the value:

description: Specify the media type of the response to be returned.

15. Add a new line and click example in the shelf.

106
16. Set the example to application/xml.

17. Similarly, add a description node to the Cache-Control header of the response.
18. In the description node line, type | and press enter.
19. Return to the course snippets.txt file.
20. Locate the Description for Cache-Control header under Module 7 and copy the lines of text.

21. Return to API designer, press tab in the new line and paste the text in the new empty line.

Note: Fix the indentation for the last two lines of the description, by going to the beginning of the
line and pressing tab to align it with the first line.

22. Add a new line below the description node.

23. Press backspace or delete to go back one tab space.
24. In the shelf, click example.

107
 25. Set the example node to private, max-age=31536000.
26. Similarly, set the following documentation nodes for the Expires header:

• description: The text for Description for Expires header text in the course snippets.txt file
• example: Tue, 18 Apr 2017 09:30:41 GMT
• format: rfc2616

Note: The default datetime format follows rfc3339 specification.

Add documentation to other request and response headers

27. In the /customers resource post method, add a description to the Location headers for the \

description: URL of the new customer information

28. Press enter to add a new line and add an example node.
29. Type the following value for the example node:

/customers/8f19cb50-3f57-4d38
30. In the file browser, expand the datatypes folder and click CustomErrorMessage.raml.
31. On your computer, return to the course snippets text file.
32. In the Module 7 section, copy the example data for the CustomErrorMessage datatype.
33. Go back to API designer, add a new line at the end of CustomErrorMessage fragment file.

108
 34. Paste the lines and fix the indentation.

View the API console

35. In the API console, under the /customers resource, click GET.

36. In the Request section, verify that you can view the Accept header description and example
data.

37. Click the back arrow, to go back to the list of resources.

109
Walkthrough 7-3: Use the mocking service in API console to test
an API
In this walkthrough, you will test your API by enabling mocking service. You will:

• Enable the mocking service in the API console.

• Test a few methods in the API console to see the response information.

Enable the mocking service in the API console

1. Return to API designer.
2. In the top-right corner of the API console, click the Mocking Service toggle button.

110
 3. Verify that the toggle button now contains a check mark.

4. Look at acme-banking-api.raml in the RAML editor; you should now see a new baseUri
parameter was added above the title node.

Test a method in the API console to see the response information

5. In the API console, under the /{customer_id} resource, expand it and click GET.

6. Click Try it.

111
7. In the URI parameters field, enter any value as customer_id and click Send.

8. Verify that you can view the Response status and information.

9. Toggle the mocking service to turn it off.

112
Module 8: Making APIs
Discoverable

Objectives:

• Publish API specifications and fragments to Anypoint Exchange for discovery.

• Create Exchange portals for learning about and testing APIs.
• Customize Exchange public portals with themes.
• Create a sample use case with API Notebook inside Exchange portals.
• Gather feedback from API consumers.

113
Walkthrough 8-1: Publish a RAML API fragment to Anypoint
Exchange
In this walkthrough, you promote reusability of an API fragment by publishing it to the private
Anypoint Exchange. You will:

• Create an API Fragment project in Design Center.

• Publish an API Fragment to Anypoint Exchange.
• Consume the fragment from Anypoint Exchange.

Create an API fragment project in Anypoint Platform Design Center

1. In the top-left corner, click the back arrow; this will navigate to the list of projects page.

2. In the Design Center homepage, click the Create button next to the search bar.
3. In the New Project dialog box, type the Project name as Banking DataTypes.
4. In the Project Type field, click the drop-down menu and select API Fragment.
5. In the Fragment Type field, click the drop-down menu and select Data Type.
6. Click Create.

114
 7. In API designer, click the menu icon in the Files section header.

8. Click Import.
9. In the Import dialog box, click Choose File.
10. Navigate to the APDevApiDesign3.9_studentFiles folder and select bankingDatatypes.zip file.
11. Click Import.

12. In the file browser, click the menu icon next to banking-datatypes.raml.

13. Click Delete.

Publish an API Fragment to Anypoint Exchange

14. In the top right corner of the webpage, click the Publish to Exchange icon.

115
 15. In the Publish API Fragment to Exchange dialog box, click Publish.
16. Verify that you see a dialog box with a message that the Banking datatypes project was
successfully published to Exchange.

17. Click Done.

Consume an API Fragment from Anypoint Exchange

18. In the top left corner, click the back arrow.
19. In the Design Center homepage, click the ACME Banking API project.
20. In the file browser, click the Exchange dependencies icon below the file icon.

21. Click the + icon in the Dependencies header section.

22. In the Consume API Fragment dialog box, check the box for Banking datatypes API fragment.

116
23. Click the Add 1 Dependency button.
24. Verify that you can view the path to the asset added as dependency from Exchange and click
Ok.

25. Click the Files icon to the top-left next to the Dependencies section header.

26. In the file browser, click the acme-banking-api.raml file.

27. In the RAML editor, go to the lines that contain the types definition.
28. In the file browser, expand the exchange_modules folder to view the datatype fragment files.

29. Hover over the Customer.raml file, and click the menu icon that appears next to it.

117
30. Click Copy path to clipboard.
31. In the acme-banking-api.raml file, replace the include path for the Customer datatype with the
path that you copied.

32. Similarly, repeat the steps to change the include path for Account and Transaction datatypes.

33. In the file browser, expand the datatypes folder.

34. Click the menu icon next to the Account.raml file and click Delete.

35. Similarly, delete the rest of the datatype files except the CustomErrorMessage.raml file.
36. In the API console, expand the Types section.
37. Verify that you see the Customer, Account and Transaction datatypes from exchange
dependencies listed.

118
Walkthrough 8-2: Publish a RAML API specification to Anypoint
Exchange
In this walkthrough, you enhance the discoverability of an API by adding it to the private
Anypoint Exchange. You will:

• Publish a RAML API Specification to Anypoint Exchange.

• Add documentation to an asset in Exchange portal.
• Publish and view the Exchange portal.

Publish a RAML API Specification to private Exchange

1. Return to API designer.
2. In the top right corner, next to the username initials, locate and click the Publish to Exchange
button.

119
 3. In the Publish API Specification to Exchange, click Publish.

4. Verify that you see the message in the dialog box that indicates the API Specification has been
successfully published to Exchange.

5. Click Done.

View the asset in Exchange

6. In the top left corner, click the back arrow.
7. In the main menu, click Exchange.
8. In Exchange webpage, click your business group name in the left navigation panel.

120
 9. In the list of assets in your business group, click ACME banking API.

Add documentation to an Exchange asset

10. In the ACME Banking API asset page, click Edit in the center of the page to add information
about the asset.

11. Go to APDevApiDesign3.9_snippets.txt.
12. In Module 8 section, copy the content under ACME Banking API Exchange content.

121
13. Return to Exchange 2.0 webpage and paste the content.

14. In the bottom left corner of the editor, click the Save as draft button.

15. In the Exchange asset details panel on the left, click the Publish button to add the content
information to the asset.

122
16. Verify that you are redirected to the Asset homepage, with the information about the asset listed
in the center panel.

123
Walkthrough 8-3: Add an API specification to the public portal
In this walkthrough, you will add an API to the public portal and customize the developer portal.
You will:

• Add an API asset in the public portal.

• Define a color scheme for the public portal.
• Publish and view the resulting portal.

Create an API Portal

1. In the right side of the ACME Banking API Exchange asset page, click Share.

2. In the Share ACME Banking API dialog box, click the add to public portal link.

124
 3. Select the version v1 checkbox and click Share.

View the public portal

4. In the left navigation in ACME Banking API asset page, click Assets list.
5. In the left navigation of Exchange assets page, click Public Portal.

6. Verify that you see the ACME Banking API asset listed in the public developer portal page.

125
Customize the public portal
7. In the top-right corner of the developer portal page, click Customize.

8. In the right panel, locate the Top bar Logo field and click Choose file.
9. In the file chooser dialog, browse to APApiDesign3.9_studentFiles directory and select the
MuleSoft_Dev_Logo.png.
10. Click Open.

Define a color scheme for the public portal

11. In the right panel, click the Background color hex code and copy the Text color (active) blue
color value and paste it as the background color.

12. Change the Text color (active) hex code value to #000000.

126
13. In the top-right corner, click Done editing.

14. In the Publish changes dialog box, click Yes, publish.

15. Verify that the changes have been made to your public developer portal.

127
Walkthrough 8-4: Create a sample use case with API Notebook
inside the Exchange portal
In this walkthrough, you create an API Notebook inside the API Portal. You will:

• Add an API Notebook page in the Exchange portal.

• Perform string manipulation on datatypes.
• Create and use JavaScript functions inside API Notebook.
• Publish the API Notebook page in the Exchange portal.

Add an API Notebook in the API Portal Designer

1. Return to the ACME Banking API asset details page in Exchange.
2. In the top right corner, click Edit.
3. In the left navigation, click Add new page.

128
4. Type the name as API Notebook, and click Enter.

5. In the ACME Banking API content editor, click the icon to the right side of the picture icon.

6. In the content editor, change the first parameter in the createClient function from ‘client’ to
‘acmeBankclient’.

7. At the bottom of the content editor, click Save draft

8. Click Play notebook link.

129
 9. Verify you get a $0= message for the function call, below the code cell.

Insert a code cell to explore the ACME Banking API

10. In the top-right, click Edit.
11. In the content editor, add a new line below the first createClient function call.
12. Add a text line:

Retrieve a list of customers.

13. Add two new lines, and click the notebook icon to the right of the picture icon.
14. Type the following code within the notebook code cell:

acmeBankClient.customers.get();

Access the customer datatype example and its attributes and nested datatypes
attributes in the API Notebook
15. Add a new line, and type the following:

Retrieve a specific customer information

16. Return to APApiDesign3.9_snippets.txt file, and copy the JavaScript code snippet for the code
cell value to retrieve a specific customer in Module 8.
17. Return to API Notebook page, press enter two times and click the notebook icon to the right of
the picture icon and paste the Javascript code snippet inside the code notation.
18. In the same code cell, place the cursor at the beginning of the code cell and type customerA=.

130
 19. Add a new line, and type:

Retrieve customerA’s displayName

20. Add two new lines, and click the notebook icon to the right of the picture icon and type the
following:

customerA.body.displayName
21. Click Save as draft.
22. Click Play Notebook.
23. Verify that you can see the result of all the code cells.

Perform string manipulation on the datatypes

24. In the top right corner, click Edit.
25. In the API Notebook content editor, add a new line and type:

Retrieve a specific account information.

26. Add two new lines and return to APApiDesign3.9_snippets.txt and copy the code from Module 8
with the heading Code cell value to retrieve a specific account information.

131
27. Return to API Notebook content editor, and paste it in a code cell (by clicking the notebook icon).

28. Click Save as draft.

29. Scroll down to the accountA code cell, and click Play.
30. Verify that you can view the values for accountBalance, accountOwner, and the Bank object.

31. In the top-right corner, click Edit.

32. Add a new line and type:

Convert accountBalance into a number

33. Add two new lines, return to APApiDesign3.9_snippets.txt and copy the JavaScript snippet from
Module 8 with the heading - Code cell value to convert accountBalance amount into number
from string.
34. Return to API Notebook content editor, click the notebook icon and paste the snippet in the
code area.

132
 35. Add a new line, and type:

Write an if statement to print reward values based on account balance

36. Add two new lines.
37. Return to the APApiDesign3.9_snippets.txt, copy the JavaScript snippet from Module 8 with the
heading Code cell value for a conditional statement.
38. Return to API Notebook content editor, click the notebook icon and paste the snippet in the
code area.

Create and use JavaScript functions inside the API Notebook

39. Add a new line, and type:

Write a function to concatenate currency and amount attributes from

the accountBalance property
40. Add two new lines, and return to the APApiDesign3.9_snippets.txt, copy the JavaScript snippet
from Module 8 with the heading Code cell value for a function to concatenate and display
currency and amount.
41. Return to API Notebook content editor, click the notebook icon and paste the snippet in the new
code area.

133
 42. Click Save as draft.
43. In the top-right panel, click Publish.

View the API Notebook in the Live Portal

44. In the API Notebook page, click Play Notebook link.
45. Verify that you see the results returned below each cell in the API Notebook.

134
Module 9: Reusing Patterns

Objectives:

• Create and reference resource type patterns for reusability.

• Use traits to modularize methods.

135
Walkthrough 9-1: Define and use a resource type for resources
that perform operations on a collection
In this walkthrough, you define a collection resource type to reuse some parts of the method
definition for resources that perform operations on a collection. You will:

• Define a collection resource type fragment.

• Use a mapping to pass parameter values to a resource type.
• Reference the resource type in the RAML API definition.

Define a collection resource type fragment

1. In the Anypoint Platform webpage, click the menu icon.
2. Select Design Center.
3. In the Design Center projects page, click ACME Banking API.

136
4. In the file browser, click the + icon next to the Files header, and select New folder.

5. In the Add new folder dialog box, set the name of the folder to resourceTypes.
6. Click Create.
7. In the file browser, hover over the resourceTypes folder and click the + icon.
8. Select New file.
9. In the Add new file dialog box, click the drop-down box next to the Specification field, and select
Resource Type.

10. Rename the file as collection.raml.

11. Click Create.
12. In the file browser section, click acme-banking-api.raml to open the RAML definition file.
13. In the /customers resource, cut the post method definition.
14. In the file browser, expand the resourceTypes folder and click collection.raml.

137
 15. Paste the lines after the first line in collection.raml.

Note: Select the pasted lines and press Shift + Tab to move a tab space to the left and properly
indent the lines.

Use mappings to pass parameter values to resource types

16. In the collection.raml resource type file, go to the line that contains the description for the post
method.
17. Replace the word customer with <<resourcePathName | !singularize>>

18. Similarly, in the displayName node, replace the word customer with <<resourcePathName
| !singularize>>.
19. Similarly, in the description node for the Location header, replace the word customer with
<<resourcePathName | !singularize>>.
20. Similarly, in the example for the location header, replace customers with
<<resourcePathName>>.
21. Locate the line of code that contains the post request body type Customer.
22. Delete the Customer datatype and set it to the following:

<<resourcePathName | !singularize | !uppercamelcase>>

23. Go to the line that contains the HTTP 503 response body type CustomErrorMessage and
replace the value as:

type: !include ../datatypes/CustomErrorMessage.raml

24. Make the post node an optional method.

Reference the resource type in the RAML API definition

25. In the file browser, select acme-banking-api.raml.

138
26. Add a new line before the /customers resource and add the resourceTypes node:

resourceTypes:

27. In the new line, include the collection resourcetype by typing:

collection: !include resourceTypes/collection.raml

28. Press enter.

29. In the /customers resource, add a new line before the get method.

Note: Indent the new line at the same tab level as the get method.

30. Reference the type collection and add the mapping values by typing:

type: collection
31. Add the post method in the line before the get method definition.

32. Similarly, go to the /accounts main resource and delete the post method definition.
33. In the /accounts main resource, in the empty line, reference the collection resource type:

type: collection
34. Add the post method node below the reference to the collection resource type.

139
 35. Similarly, in the /transactions main resource, delete the post method definition and add a
reference to the collection resource type.

View the documentation

36. In the API console, go to the list of resources.
37. Locate the /customers resource.
38. Click POST, and verify that you see the method details.

140
Walkthrough 9-2: Define and use a resource type for resources
that perform operations on a member
In this walkthrough, you define a member resource type to reuse some parts of the method
definition for resources that perform operations on a member. You will:

• Define a member resource type fragment.

• Use mappings to pass parameter values to the resource type.
• Reference the resource type in the RAML API definition.

Define a member resource type fragment

1. Return to API designer.
2. In the file browser, hover over the resourceTypes folder and click the + icon.
3. Select New file
4. In the Add new file dialog box, select the file type as Resource Type, and rename it as
member.raml.
5. Click Create.
6. In the file browser, select acme-banking-api.raml.

141
7. Locate the /{customer_id} resource and cut all the lines for the get, patch and delete methods.

8. In the file browser, click the resourceTypes/member.raml file.

9. Paste the copied lines after the first line in member.raml.
10. Select the pasted lines and press Shift+tab two times to indent the lines properly.
11. Go back to acme-banking-api.raml and locate the /{account_id} method.
12. Cut the lines for the put method definition.

142
 13. Go to member.raml and paste the put method below the delete method definition.

Note: Make sure to fix the indentation.

14. In member.raml file, add the optional attribute to all the methods.

Use mappings to pass parameter values to resource types

15. In the get method, go to the line that contains the description, replace the value as:

Retrieve a/an <<resourcePathName | !singularize>> with a specific

<<resourcePathName | !singularize >>

16. Similarly, replace the displayName node value with:

Get a/an <<resourcePathName | !singularize>> by <<resourcePathName |

!singularize>> ID
17. Go to the line that contains the HTTP 200 response body type Customer.

143
 18. Delete the type value Customer, and replace it with <<resourcePathName | !singularize |
!uppercamelcase>>.
19. Go to the HTTP 404 response body and replace the CustomErrorMessage datatype with
!include ../datatypes/CustomErrorMessage.raml.
20. Similarly, replace the patch and delete method description, displayName, and error response
body types with similar mappings.

21. In the put method definition replace the 200-response body type with an in-built mapping and
the 501-response body type with the include statement for the CustomErrorMessage datatype.

Reference the member resource type fragment in the RAML API definition
22. In the file browser, select acme-banking-api.raml.
23. Go to the resource type definition section above the /customers resource, and add a new line
below the collection resource type.

144
24. In the new line type:

member: !include resourceTypes/member.raml

25. Go the /{customer_id} resource and add lines to reference the member resource type with the
get, patch and delete methods.

type:
member:
get:
patch:
delete:

26. Similarly, in the /{account_id} nested resource, delete the get, put, and delete methods.
27. Reference the member resource type with the custom mappings for example, custom error
message and include the get, put and delete methods.

type:
member:
get:
put:
delete:

145
 28. Similarly, reference the member resource type for the /{transaction_id}: nested resource with
custom mappings and include only the get method.

View the API console

29. In API console, go to the list of resources.
30. Locate and expand the /accounts/{account_id} resource.

31. Click GET.

146
32. Scroll down and verify that you see the HTTP 200 response body contains the Account
datatype.

147
Walkthrough 9-3: Define and use various traits for resources and
methods
In this walkthrough, you refactor the API definition by creating reusable traits for resources and
methods. You will:

• Consume a cacheable trait asset from Anypoint Exchange.

• Define a flexible content type trait to be applied to the resource method with an Accept
header in the request.
• Refactor the resource methods to use these traits.

Consume a cacheable trait asset from Anypoint Exchange

1. Return to API designer.
2. In the file browser section, click the Exchange dependencies icon.

3. Click the + icon next to the Dependencies header.

148
 4. In the Consume API Fragment dialog box, locate Training: Cacheable Trait and check the box.

5. Click Add Dependency.

Reference the cacheable trait inside a RAML API Specification

6. In the file browser, click the files menu icon.
7. In the file browser, click acme-banking-api.raml ;if the file is not open in the RAML editor.
8. Locate the line that includes the member resource type file and add two new lines below it.
9. Remove indentation in the second new line created.
10. From the shelf, click traits.
11. In the new line, type:

cacheable: !include
12. In the file browser, expand the exchange_modules folder to locate the Cacheable.raml trait file.
13. Click the menu icon next to the file name, and click Copy path to clipboard.

149
 14. In the RAML editor, paste the path to the traits file after the !include keyword.

Note: If you imported the Cacheable.raml file from the studentFiles folder into a traits folder,
include the path as traits/Cacheable.raml.

Refactor a resource method to use the cacheable trait

15. In the /customers resource get method 200 response, delete the lines that define the response
headers.

16. Add a new line below the line that contains the displayName for the get method.
17. In the shelf below, click is.
18. In the shelf, click cacheable.

19. In the API console, if you see an error that the ‘Property is should be an array’, change the is
node value to the following:

is:
- cacheable

150
Define an Accept header trait to apply to resource methods to support flexible
content types
20. In the file browser, click the + icon in the Files header.
21. Select New folder.
22. In the Add new folder dialog box, type the name as traits.

Note: If you have already created a traits folder, do not recreate another one.

23. In the file browser, locate the traits folder and click the + icon.
24. Select New file.
25. In the Add new file dialog box, set the type of file to Trait.
26. Rename the file to hasAcceptHeader.raml and click Create.
27. In the file browser, click acme-banking-api.raml.
28. Go to the /customers resource get method.
29. Select the lines from headers to the example line for the Accept header and copy them.

30. In the file browser, click hasAcceptHeader.raml and paste the lines in the second line.

Note: Fix the indentation.

31. In the file browser, click acme-banking-api.raml.

151
32. In the /customers get method responses, copy the HTTP 406 response lines.

33. In the file browser section, click hasAcceptHeader.raml.

34. Paste the copied lines below the responses node.

Note: Fix the indentation.

35. Go to the line in the 406 response body that contains the type and replace the type value with
an include statement to the CustomErrorMessage datatype.

36. In the file browser, click acme-banking-api.raml.

37. Locate the line that includes the cacheable trait, and add a new line below it.
38. Include the hasAcceptHeader trait.
39. Go to the /customers resource get method, and delete the lines that define the Accept header
and the HTTP 406 response.

152
 40. In the /customers resource get method, go to the line that contains the cacheable trait applied
and change the line to:

is:
- cacheable
- hasAcceptHeader

View the API console

41. In the API console, go to the list of resources.
42. Locate the /customers resource, and click GET.
43. Verify that you can view Traits applied at the top of the resource method details page.

153
Module 10: Modularizing APIs

Objectives:

• Use libraries for greater API composability.

• Override resource information using overlays.
• Use overlays to internationalize resources.
• Use extensions to enhance resources.

154
Walkthrough 10-1: Create and use a library of traits
In this walkthrough, you will create a library file with several traits listed in them. You will:

• Create a library fragment file.

• Refactor and move existing traits inside the library file.
• Create and define new resource method request and response traits.
• Refactor the API definition to reuse the traits from the library.

Create a library file

1. Return to API designer.
2. In the file browser, click the + icon in the Files header section.
3. Select New folder.
4. In the Add new folder dialog box, type the name of the folder as libraries.
5. Click Create.
6. In the file browser, locate the library folder and click the + icon.
7. Select New file.
8. In the Add new file dialog box, select the file type as Library.
9. Rename the file as TraitsLibrary.raml
10. In the RAML editor, go to the usage node and type the value as:

Use the following traits to define request and response headers and
response status information

155
Define traits for response information in the library file
11. In the traitsLibrary.raml file, add two new lines.
12. In the shelf, click traits.
13. In the new line type:

hasGetResponse:
14. Add a new line below.
15. In the file browser, select acme-banking-api.raml.
16. Go to the /accounts nested resource get method, and cut the lines from the responses to the
HTTP 404 response body type CustomErrorMessage.

17. In file browser, select TraitsLibrary.raml and press tab in the new line.
18. Paste the copied lines.

Note: Fix the indentation.

19. Go to the line that contains the HTTP 200 response body type Account[] and replace it with:

type: <<resourcePathName | !singularize | !uppercamelcase>>[]

156
 20. In the HTTP status 404 body type, delete the reference to CustomErrorMessage datatype, and
type:

!include ../datatypes/CustomErrorMessage.raml

Apply the traits in the main RAML API definition

21. In the file browser, select acme-banking-api.raml.
22. Cut the cacheable and hasAcceptHeader reference lines and delete them from acme-banking-
api.raml.

Note: Delete the traits node entirely in the acme-banking-api.raml file.

23. In the file browser, select traitsLibrary.raml and add the copied lines before the
hasGetResponse trait definition.
24. To get rid of the error in lines that include the traits fragment, add ../ before the trait's path in the
include statement.
25. In the file browser, select acme-banking-api.raml.
26. Go to the empty line after the resourceTypes definition and add a new line.
27. In the shelf, click uses.

157
28. In the new line type:

Traits: libraries/traitsLibrary.raml.
Note: Add empty lines below the Traits definition and above the uses node to increase
readability.

29. In the /customers resource get method, go to the line that applies the traits cacheable and
hasAcceptHeader and add Traits. before the traits name:

is:
- Traits.cacheable
- Traits.hasAcceptHeader

30. In the /accounts nested resource get method.

is:
- Traits.hasGetResponse

158
 31. Similarly, in the /transactions nested resource get method, delete the lines that define the get
method response and apply the hasGetResponse trait.

View the API console

32. In API console, go to the list of resources.
33. Locate and expand the /customers/{customer_id}/accounts resource and click GET.

159
34. Verify that the hasGetResponse trait has been applied to the resource.

160
Walkthrough 10-2: Internationalize documentation and resource
description using an overlay
In this walkthrough, you internationalize the ACME Banking API using overlays. You will:

• Create a RAML overlay fragment file.

• Add documentation and resource method description nodes in the overlay file to support
Spanish localization.

Create a RAML overlay file

1. Return to API designer.
2. In the file browser section, click the + icon next to the Files header and select New folder.
3. In the Add new folder dialog box, set the name to overlays and click Create.
4. In the file browser, click the + icon next to the overlays folder and select New file.
5. In the Add new file dialog box, select the file type as Overlay and set the name to
internationalization.raml and click Create.

161
Add documentation and description nodes to support Spanish localization
6. In the second line that contains the extends node, type the value as

../acme-banking-api.raml

7. Enter a new line before the extends node and type:

usage: Spanish localization.

8. Return to the APDevApiDesign3.9_snippets.txt file.
9. Copy the text from the Module 10, Spanish documentation snippet and paste it in
internationalization.raml.

10. From the APDevApiDesign3.9_snippets.txt file, copy the lines under the Spanish localization for
method description heading.
11. Return to API Designer and enter a new line below the documentation node and place the
cursor at the beginning of the line.
12. Add a new line and paste the copied text.

Note: If you observe errors that mention that the mentions invalid media type at…, there is an
issue with the RAML JS parser. The fix will be available soon. Till then, you could add the media
type application/json with every request and response body in the acme-banking-api.raml file.

View the documentation

13. In the API console, verify that the documentation, resources, and types show up similar to
acme-banking-api.raml.

162
14. Go to the Documentation section, and expand the documentation title to view the Spanish
localization of the document.
15. Go to the /customers resource and click GET.
16. Verify you can view the GET method description in Spanish.
17. Click the back arrow to go one level back.

163
Walkthrough 10-3: Define and use API extensions to promote
portability to test in multiple environments
In this walkthrough, you will define an extension. You will:

• Create API extension files.

• Add a baseUri parameter to the extension files and enter a placeholder for environment
specific implementation URL.

Create API extension files

1. Return to API designer.
2. In the file browser, click the + icon in the Files header section and select New folder.
3. In the Add new folder dialog box, set the name to extensions and click Create.

4. Click the + icon next to the extensions folder and select New file.

164
 5. In the Add new file dialog box, set the file type to Extension and set the name to
stagingExtension.raml and click Create.

6. Create two more extension files in the extensions folder called devExtension.raml and
prodExtension.raml.

Add the baseUri node to the extension files and enter a placeholder for
environment specific implementation URL
7. In the file browser, locate the extensions folder and select stagingExtension.raml.
8. Go to the line that contains the extends node and type the value as:

../acme-banking-api.raml

9. In API console, turn on the mocking service at the top right corner.

165
10. Verify that you see the baseUri added to the extension file.

Note: You can replace the Mock service URL with a staging environment specific
implementation URL.

11. In API console, click GET for the /accounts/{account_id} resource.

12. Click Try It.
13. Enter the account_id value as 12345 and click GET.
14. Verify that you see the response structure of the get method.

166
 15. Similarly, go to the devExtension.raml file and include the acme-banking-api.raml file in the
extends node.
16. Add a new line before the extends node, and type the following:

baseUri: <<insert dev environment specific implementation URL>>

17. Similarly, in the prodExtension.raml file, add in a placeholder for the baseUri and reference
acme-banking-api.raml in the extends node.

Extend a resources’ functionality using an extension fragment

18. In the prodExtension.raml file, add two new lines below the baseUri.
19. In the new line type the following:

/transactions:
type:
member
put:

167
View the extended resource method in API console
20. In the API console, verify that you see the /transactions resource moved up to the top.

21. Expand the /{transaction_id} resource, and verify that you can view the PUT method.

22. Click PUT.

168
23. Verify you can view the put method details.

169
Module 11: Securing APIs

Objectives:

• Define API security requirements.

• Use security schemes to apply resource and method level policies.
• Define custom security scheme for APIs.
• Apply an OAuth2.0 external provider policy to resource methods.

170
Walkthrough 11-1: Define a custom security scheme for an API
In this walkthrough, you will define a custom security scheme for your API. You will:

• Create a custom security scheme file.

• Reference the custom security scheme in the main RAML API definition.
• Apply the security scheme to certain resource methods.

Create a security scheme file

1. Return to API designer.
2. In the file browser, click the + icon next to the Files header.
3. Select New folder, and in the Add new folder dialog box, enter the name as securitySchemes.
4. Click Create.
5. Click the + icon next to the securitySchemes folder, and select New file.
6. In the Add new file dialog box, select the file type as Security Scheme and rename the file as
customTokenSecurity.raml.

171
 7. Click Create.

Define a custom security scheme

8. In the RAML editor, go to the line that contains type node and press space bar after the colon.
9. In the shelf below the editor, click x-{other}.

10. Replace {other} with customToken.

11. Add a new line below the type node.
12. In the shelf, click description.
13. Type the value of the description node as:

This security scheme validates requests to the API using a token

provided in the request header
14. Press enter to add a new line.

15. In the shelf, click describedBy.

172
 16. In the shelf, click headers.

17. In the shelf, click Authorization.

18. In the shelf, click description.

19. Type the value of the description node as: This header should contain a valid security token.
20. Press enter to add a new line.
21. In the shelf, click type.
22. In the shelf, click string.

Reference the custom security scheme file in the main API definition
23. In the file browser, select acme-banking-api.raml.
24. Go to the empty line after the line that references the traitsLibrary file.
25. Add two new lines below it.
26. Remove indentation in the second new line created.

173
 27. From the shelf, click securitySchemes.

28. In the new line, type:

customTokenSecurity: !include securitySchemes/customTokenSecurity.raml

Apply the custom security scheme to all the resource methods in the API
29. Go to the empty line before the /customers resource and press enter.
30. In the shelf, click securedBy.

31. In the shelf, click customTokenSecurity.

174
 32. Press enter to add a new line.

View the documentation

33. In API console, locate the /customers resource and click GET.
34. Locate the Headers section of the Request, and verify that you can see the Authorization
header field listed.

Note: Go to any other resource method and notice the Authorization header added to all the
resource methods by adding to the root of the RAML definition. Custom security schemes like
the customTokenSecurity are not supported for testing using the Try It option.

175
Walkthrough 11-2: Consume an OAuth2.0 security scheme for an
API and secure API resources
In this walkthrough, you define a security scheme to secure API resources using OAuth2.0.
You will:

• Consume an OAuth2.0 security scheme fragment file.

• Reference the OAuth2.0 security scheme in the RAML API definition.
• Apply the security scheme in the API resource methods.

Consume an OAuth2.0 security scheme fragment file

1. Return to API designer.
2. In the file browser, click the Exchange dependencies icon.

3. Click the + icon next to the Dependencies header.

176
 4. In the Consume API Fragment dialog box, locate Training: OAuth2.0 Security Scheme and
check the box.

5. Click Add Dependency.

Reference the OAuth 2.0 security scheme inside a RAML API Specification
6. In the file browser section, click acme-banking-api.raml ;if the file is not open in the RAML editor.
7. Locate the customTokenSecurity include statement and add a new line below it.
8. In the new line, type:

oauth2_0: !include
9. In the file browser section, expand the exchange_modules folder to locate the OAuth2.raml
security scheme file.
10. Click the menu icon next to the file name and click Copy path to clipboard.

177
 11. In the RAML editor, paste the path to the traits file after the !include keyword.

Note: If you imported the OAuth2.raml file from the studentFiles folder into a traits folder, include
the path as securitySchemes/OAuth2.raml.

Secure the resource methods that update bank customer and account
information with the OAuth2.0 security scheme
12. In the /{customer_id} resource patch method, add a new line below the line that contains the
displayName node.
13. In the shelf, click securedBy.

14. In the shelf, click oauth2_0.

15. In API console, locate the /customers resource and click GET.

178
16. Scroll to the Request Headers section, and verify that you can see an Authorization header.

17. Click the Try it button.

18. Select the Authorization and verify that the you need to fill the Auth data to send a request.

179
Module 12: Enhancing API
Responses using Hypermedia

Objectives:

• Describe hypermedia.
• Simplify API discoverability using hypermedia.
• Use hypermedia to enhance API responses.
• Modify API definitions to generate state-specific client responses.

180
Walkthrough 12-1: Modify an API definition to implement state-
specific client responses
In this walkthrough, you add state specific responses for methods that add data into the API
implementation and go through multiple stages of processing information. You will:

• Create an HTTP 202 post body response with necessary headers.

• Add a new resource to track the state of post requests that are under processing.
• Add necessary HTTP methods with responses to give meaningful information back to
the API consumers.

Create an HTTP 202 post body response with necessary headers

1. Return to API designer.
2. In the file browser, expand the resourceTypes folder and select collection.raml.
3. Go to the line that contains the HTTP response status 503 and add a new line above it.

4. Align the cursor with the start of the next line and type
202:
5. Add a new line below the response status line.
6. In the shelf, click description.
7. Type | and add a new line.

181
 8. In the new line, type the following sentence:

The request has been accepted for processing. Use the URI provided in the Location
header in the response to monitor the status.
9. Press enter.
10. In the shelf, click headers.
11. In the shelf, scroll down and click Location.
12. In the shelf click example.
13. Type the value of the example node as:

/<<resourcePathName>>/1234/status

Add a new resource to track the state of post requests that are under processing
14. Return to acme-banking-api.raml.
15. Go to the empty line before the /accounts main resource, and press enter.
16. Place the cursor in the previous empty line.
17. Press tab to align the cursor with the /accounts nested resource beginning and type:

/status:

Add necessary methods and HTTP response statuses to give meaningful

information back to the API consumers
18. In the file browser, click the + icon next to the resourceTypes folder, and create a new resource
type file with the name stateSpecificResourceType.raml.
19. In stateSpecificResourceType.raml, add a new line below the first line.

182
20. In the shelf, click get.
21. In the shelf, click responses.
22. In the shelf, click 200.
23. In the shelf, click description.
24. Type the value of the description node as:

The API is still processing the request

25. Add a new line and in the shelf, click body.

26. In the shelf, click application/json.
27. In the shelf, click example, and type the value as:

{ “status”: “Working”}

28. Press enter to add a new line.

29. Copy the lines containing the details for the 200 response paste it in the new empty line.
30. Press enter and paste the lines again.
31. In the first set of pasted lines, replace 200 with 303 and fix the indentation.

32. Edit the description node value to:

The processing has finished successfully. Use the URI provided in the Location header
for more details.
33. Press enter after the description to add a new line.

183
 34. In the shelf, click headers.
35. In the shelf, click Location.
36. In the shelf, click example, type the value as:

/<<resourcePathName>>/1234

Note: Always add a space between the node and the value

37. In the response JSON example, change the status value from Working to Success.
38. In the second set of pasted lines, change the status code from 200 to 503 and correct the
indentation.

39. In the description node below the 503 status code line, change the value of the node to:
The processing has failed

40. In the response JSON example, change the status value from Working to Failed.

Include the state specific resource type in the root RAML definition
41. In the file browser, select acme-banking-api.raml.
42. Go to the resourceType include statements at the root and add a new line below the member
resourceType.
43. Indent the line and type:

stateSpecific: !include resourceTypes/stateSpecificResourceType.raml

44. Add a new line below the line that contains /status nested method and press enter.

184
 45. Press tab and type:

type: stateSpecific

View in API console

46. In API console, locate the /customers/{customer_id}/status resource and click GET.

47. Scroll down to the response, and verify that you can see the various status codes for the
responses.

185
Module 13: Versioning APIs

Objectives:

• Explain when and when not to version APIs.

• Describe the methods for versioning APIs.
• Document changes in new API versions using Exchange portals.
• Deprecate older versions of APIs.

186
Walkthrough 13-1: Add a new API version
In this walkthrough, you create a new version of the ACME Banking API. You will:

• Create a new API version in Design Center.

• Learn how to publish the new version to Exchange and API Manager.
• Deprecate the old version of the API.

Add a new version of API definition in the API Designer

1. Return to API designer.
2. Click the branch icon on top with the active master branch next to it.

3. In the Find or create a branch search text box, type v1 and click create v1 branch from master.

Note: This way the master branch always points to the most latest version of the API being
designed.

187
 4. In the RAML editor, verify that the acme-banking-api.raml file is open.
5. Replace the value of the version field with v2.

Note: Now you are all set to make changes to the master branch v2 version of the ACME
Banking API.

Verify that you can publish the new version of the API to Exchange
6. In the API designer page, click the Publish to Exchange button on the top right corner.

7. In the Publish API specification to Exchange dialog box, verify that the asset version and the
API version are set to the 2.0 numbers respectively.

Note: We will not publish v2 into Exchange yet, since v1 is not live and being consumed yet.
Only managed and live APIs should be versioned.

The new version of an API in Exchange, will have a separate API Portal page for documentation
purposes.

8. Click Publish.

188
Deprecate the older version of the API
9. In the Publish API Specification dialog box, click Exchange.
10. In the ACME Banking API asset details page, click the down-arrow next to v2.

11. In the ACME Banking API v1 asset details page, locate the Asset versions for v1 section in the
right.
12. Click the three vertical dots next to version 1.0.0.
13. Click Deprecate version.

14. In the Deprecate asset version dialog box, click Deprecate version.
15. Verify that you see a yellow deprecated banner on top of the page.

189