Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Understanding API Design

DZone's Guide to

Understanding API Design

This in-depth guide to API design will help you understand the types of APIs, their structure, and how to make calls and navigate them.

Free Resource

The Integration Zone is brought to you in partnership with Cloud Elements.  What’s below the surface of an API integration? Download The Definitive Guide to API Integrations to start building an API strategy.

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

Image title

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. 

Image title

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.

Image title

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

Image title

View the Airport Information Webservice endpoint WSDL.


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

Image title

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.

Image title

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.

Image title

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

12. Click Invoke.

Image title

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

Image title

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

Image title

Make a Call to an RPC API

You will examine the Slack RPC API and make a call to an RPC endpoint.

Image title

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.

Image title

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.

Image title

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

Image title

Make a call to an endpoint.

6. Scroll back up and click the Tester tab.

Image title

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

Image title

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

Image title

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.

Image title

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.

Image title

2. In the left navigation bar, click Playground.

3. On the API/Playground page, click (Empty…) on the left-hand side.


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

Image title

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.

The State of API Integration Report provides data from the Cloud Elements platform and will help all developers navigate the recent explosion of APIs and the implications of API integrations to work more efficiently in 2017 and beyond.

Topics:
mulesoft ,soap api ,rest api ,api design ,api ,integration ,anypoint platform

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}