DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Please enter at least three characters to search
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Zones

Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Last call! Secure your stack and shape the future! Help dev teams across the globe navigate their software supply chain security challenges.

Modernize your data layer. Learn how to design cloud-native database architectures to meet the evolving demands of AI and GenAI workloads.

Releasing software shouldn't be stressful or risky. Learn how to leverage progressive delivery techniques to ensure safer deployments.

Avoid machine learning mistakes and boost model performance! Discover key ML patterns, anti-patterns, data strategies, and more.

Related

  • Breaking Up a Monolithic Database with Kong
  • Building REST API Backend Easily With Ballerina Language
  • Leveraging Salesforce Using Spring Boot
  • User-Friendly API Publishing and Testing With Retrofit

Trending

  • Designing a Java Connector for Software Integrations
  • AI-Based Threat Detection in Cloud Security
  • Unmasking Entity-Based Data Masking: Best Practices 2025
  • Docker Base Images Demystified: A Practical Guide
  1. DZone
  2. Software Design and Architecture
  3. Integration
  4. Understanding API Design

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.

By 
Nagarjunareddy K user avatar
Nagarjunareddy K
·
Sep. 26, 17 · Tutorial
Likes (14)
Comment
Save
Tweet
Share
12.3K Views

Join the DZone community and get the full member experience.

Join For Free

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.

API Web Service REST Web Protocols Design SOAP

Opinions expressed by DZone contributors are their own.

Related

  • Breaking Up a Monolithic Database with Kong
  • Building REST API Backend Easily With Ballerina Language
  • Leveraging Salesforce Using Spring Boot
  • User-Friendly API Publishing and Testing With Retrofit

Partner Resources

×

Comments
Oops! Something Went Wrong

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • support@dzone.com

Let's be friends:

Likes
There are no likes...yet! 👀
Be the first to like this post!
It looks like you're not logged in.
Sign in to see who liked this post!