Understanding API Design

Designing APIs

Objectives:

• Describe REST API architecture.

• Describe the API development lifecycle.

• Translate functional requirements for APIs into resources and HTTP methods.

• Navigate Anypoint Platform.

Types of API:

1. RAML

2. SOAP

3. RPC

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 the design-first approach for REST APIs.

Call a SOAP API

 Here, you will explore and understand a SOAP API. You will:

1. Examine an example SOAP API.

2. 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.

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 web service.

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 web service
operation.

14. Copy the content after the horizontal line in the response web page.

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."

Make a Call to an RPC API

You will examine the Slack RPC API and 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.

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.

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.

Make a Call to a REST API

Here, you will explore a REST API. You will:

1. Examine the Vimeo REST API.

2. 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.

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.

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.

• 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.

List categories:

1. Create User functionality text file, add the following categories:

• CUSTOMERS

• ACCOUNTS

• TRANSACTIONS

List detailed actions:

2. In the 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 –

1. Get a list of all customers in the bank.

2. Get customer information for a specific customer ID.

3. Register a new customer.

4. Update customer information for a specific customer ID.

5. Delete a customer with a specific customer ID.

ACCOUNTS –

1. Get a list of all accounts for a specific customer ID.

2. Get account information for a specific account ID.

3. Create a new account.

4. Update account information for a specific account ID.

5. Delete an account with a specific account ID.

TRANSACTIONS –

1. Get transactions for a specific account ID.

2. Get transaction information for a specific transaction ID.

3. Create a new transaction.

Save the file.

Translate Categories and Actions Into Resources and Methods

Specify Resources:
CUSTOMERS: Resource /customers

1. Get a list of all customers - Resource /customers

2. Register a new customer - Resource /customers

3. Get customer information for a specific customer ID - Resource
   /customers/{customer_id}

4. Update customer information for a customer ID - Resource
   /customers/{customer_id}

5. Delete a customer with a specific customer ID - Resource
   /customers/{customer_id}

ACCOUNTS: Resource /accounts

1. Get list of all accounts for a specific customer ID – Resource
   /customers/{customer_id}/accounts

2. Create a new account – Resource /accounts

3. Get account information for a specific account ID – Resource
   /accounts/{account_id}

4. Delete an account with a specific account ID – Resource
   /accounts/{account_id}

5. Update account information for a specific account ID – Resource
   /accounts/{account_id}

Specify resources for the Transactions entity.

TRANSACTIONS: Resource /transactions

1. Create a new transaction – Resource /transactions

2. Get transactions for a specific account ID – Resource
   /accounts/{account_id}/transactions

3. Get transaction information for a specific transaction ID – Resource
   /transactions/{transaction_id}

Specify HTTP methods for the actions

7. 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

8. Save the text file.