Introduction

This tutorial is a concise introduction to exposing an application’s API using REST. It is programming language agnostic and focuses on the broad steps taken to expose an internal application using a REST API. Instead of focusing on coding an API, we outline the broad steps taken to expose an existing application as a RESTful API and do not go into detail, discussing design or implementation. But despite being a broad introduction, the tutorial does provide references throughout to help explore the presented topics in more detail. Consider this tutorial as a starting point for learning how to design a RESTful API clients might actually use.

After completing this tutorial, consider completing the tutorial How to Build a Java RESTful API with Spring Boot. This tutorial discusses most of the topics presented here, but in greater detail, albeit focused on the Java programming language.

• The book Designing Web APIs: Building APIs Developers Will Love is an excellent resource for learning more about developing Web APIs. The book is not specific to RESTful APIs and also discusses RPC and GraphQL.

Enough introduction, let’s get started and learn how to expose an application using a REST API.

Exposing Your Application

So you have decided to expose your application using a RESTful API. The following seven broad steps outline how you might go about creating that API. And following these steps could mean the difference between your API being just another API on the Internet and an API that is widely used.

• Define the REST API’s intended purpose.
• Identify the resources the API will provide to clients.
• Define the format of the provided resources.
• Determine how clients will access the resources.
• Implement the API using a programming language.
• Document your API so clients can more easily use the API.
• Publish the API so clients can find the API.

There is no magic behind these seven steps, and to be accurate, they apply to any software project. A RESTful API is no different than any other software; before beginning, you should have a good idea of what it is you wish to build. You should consider questions such as the following. What service(s) is to be provided by exposing some of an organization’s resources to the public? What are the resources to be provided, and what is their format? How will clients access the resources the API makes available? How will developers implement the API? And finally, how will clients find the API and understand its use? Answering these questions will help you develop a more robust REST API. Let’s consider each of the seven steps above in turn, remembering we will not go into depth on any single topic.

• A RESTful API is an API that uses the Representational State Transfer (REST) architectural pattern to implement a Web API.

Before beginning this tutorial, you should have a good understanding of what an API does and why you wish to provide one. Here are some references to more explanation on APIs.

• API – What is an API?
• How To Use an API (The Complete Guide) [A Simple API Example].
• Restful API web site (restfulapi.net)
• Types of APIs

Step One – Define API Interactions

Let’s start by considering what our API is to accomplish. What service do we wish to provide by our API? We don’t have a particular user/stake-holder in the traditional sense; we are not developing the API for a specific organization or person. But, it helps to think of the general organization we wish to make our API available to and why. Before continuing, consider the following hypothetical business case.

Rental Listing Example

Assume we own an extremely simplified rental property management system. We wish to make our rental listings easily obtainable to external systems and thus increase our rented units. API consumers should be able to view a particular listing, view all listings, view listings by neighborhood, and view listings filtered by other criteria such as price and bedrooms.

We have a general notion of what services we wish our API to provide. We can formalize these general notions by modeling them with a use-case diagram. A use-case diagram is a concise way of capturing the interactions of a user – in this case, a generic API consumer – with our proposed system (API).

The API Consumer (remember the “consumer” is an external computer system, not a person) interacts directly with viewing a rental and viewing a neighborhood. The API can present a rental directly via the property’s Multiple Listing Service (MLS) number, or the consumer can access a rental by selecting from a rental listing. As interacting with the rental listing is optional, the View Rentals use case extends the View Rental use case. The same relationship is true for neighborhoods. Of course, a consumer might wish to obtain a list of rentals by a minimum number of bedrooms or a rental price range, and so these interactions are modeled as extending View Rentals. The use cases identified define what it is our API must allow an API Consumer to do with the API. They also help to identify the resources our API must provide, which we consider in the next section.

• Wikipedia provides an excellent introduction to use-case diagrams (Use case diagram – Wikipedia).

Step Two – Identify Resources

Before exposing our application as a web service, we must understand what resources the API is to provide. Determining the resources is an important step, as it defines what data our API will make available to external consumers.

Resources

An easy way to think of a resource is as being roughly analogous to an Object from Object-Oriented Design. However, while an Object encapsulates state and behavior (i.e., properties and methods), a resource encapsulates only state (properties). This difference is an essential distinction between a traditional object and REST’s concept of a resource.

• A resource has a type, associated data, and relationships with other resources, but no behavior.

Resources are a fundamental concept in RESTful API design. You must understand what a resource is and how to define one. The following is an excellent discussion on REST resources.

• REST API Naming Conventions

But in general, if you think of a resource as a person, place, or thing (where thing includes more abstract concepts), then you have a decent understanding of resources. However, remember, a resource does not capture the resource’s state.

API Resources vs. Business Object

It might seem tempting to simply translate an application’s business objects into a REST API’s resources. But, before concluding that an API’s resources is analogous to an application’s objects, you must consider what your API is to expose and what it should not expose. There is not necessarily a direct correlation between the two entities.

When defining an API’s resources, limit the resources to only the business objects you wish to expose.

• Many of an application’s business objects should not be exposed as REST resources.

For example, suppose our hypothetical property management system contained information on both the property itself and the owner of the property. The purpose behind our API is to expose our rental listings, but its purpose is not to expose the property owner’s personal information. And our business would most likely face severe legal consequences if we exposed an Owner’s social security number, account number, and other personal data via a public REST API. Point is, there is not a one-to-one correlation between our system’s business objects and the resources we wish to reveal.

Rental Listing Example

The use case model we created earlier argues two resources, rental property, and neighborhood. As our API is not to provide information on rental property owners, we exclude our underlying system’s Owner object.

• A resource does not include behavior. There are no methods tied to a resource. As you see in the next section, resources have methods acted upon them.

In the object model above, we model Neighborhood as have an aggregation of Rental object. This aggregation reflects that a neighborhood contains many rental properties. In JSON nomenclature, aggregations are termed resource collections. We also have a collection of Neighborhood resources and a collection of Rental resources.

These resources will be important when we define our API’s endpoints. But before considering the endpoints, let’s define our API’s message format.

Step Three – Define Message Format

RESTful APIs have two messaging formats, XML and JSON. In this tutorial, we assume a Javascript Object Notation (JSON) message format, as JSON has become the defacto standard for RESTful APIs.

JavaScript Object Notation (JSON)

If not familiar with JSON, pause to review one or more of the following resources.

• JSON explained (JSON – Wikipedia).
• RapidAPI API Glossary (JSON – What is JSON?).
• JSON.org’s introduction (Introducing JSON).

But JSON is an intuitive format to grasp, as it consists of only a few notations and is Javascript.  An object is defined by an opening and closing brace. For example, the following is an anonymous object that contains three properties, the last of which is a nested object.

{
  "name":"Mr. Foo",
  "age":"33"
  "bar":
  {
    "name":"Mr. Bar",
     "age":"45"
  }
}

Collections are defined by an opening and closing square brace, as the following illustrates.

{
  "title":"The Three Stooges Meets Hercules",
  "release-date":"1962",
  "synopsis":"Three goofy druggists travel back to Ancient Greece on a milquetoast inventor's time machine.",
  "stooges":[
    {
      "name":"Larry"
    },
    {
      "name":"Curly"
    },
    {
      "name":"Moe"
    }
  ]
}

And from these two basic concepts of resource { } and collection [ ] the remaining notation should fall into place in understanding. Refer to the JSON website for a definitive guide to JSON syntax (JSON.org).

JSON Schema

Although optional, and often skipped, defining a schema for your JSON data is also useful. A JSON schema allows validating and standardizing JSON. Moreover, the schema serves as the documentation for your API’s resources and will enable clients to generate data objects in their chosen language quickly. We do not discuss creating a schema here, nor do we discuss JSON schema syntax. However, we do illustrate a schema’s usefulness in the next few sections.

• For more details on JSON schemas, refer to the JSON Schema website.

Rental Listing Example – JSON

Translating resources to valid JSON is error-prone and tedious. However, there are several tools that help simplify converting our resources into JSON. For example, here are three tools, two paid and one free, that help defining a JSON message easier.

• Altova JSON Modeling Tool (5 Reasons to Choose a Graphical JSON Schema Editor) – Paid
• Liquid Studio’s JSON Schema Editor – Paid
• JSON Editor Online – Free

For example, using JSON Editor, we can add the objects we modeled as a hierarchical tree, create sample data, and translate the sample data into the corresponding JSON.

Although graphically translating a tree structure to JSON using a tool like JSON Editor is easier and less error-prone than creating JSON manually, we could always create JSON manually and validate it using a tool such as JSONLint.

Regardless of if we use a tool or construct JSON manually, we should always create sample JSON representing the resources modeled. The following listing is our resources with sample data formatted as JSON.

{
  "neighborhoods": [{
      "name": "Laurel",
      "zip": "21702",
      "rentals": [{
          "bedrooms": "3",
          "rent": "1500"
        },
        {
          "bedrooms": "2",
          "rent": "700"
        },
        {
          "bedrooms": "1",
          "rent": "200"
        }
      ]
    },
    {
      "name": "Dundalk",
      "zip": "21704",
      "rentals": [{
          "bedrooms": "5",
          "rent": "1500"
        },
        {
          "bedrooms": "1",
          "rent": "500"
        },
        {
          "bedrooms": "3",
          "rent": "1200"
        }
      ]
    }
  ]
}

Rental Listing Example – JSON Schema

After defining the JSON, we can formalize it into a JSON Schema using an available tool such as the commercial tools listed earlier, or using an online tool such as the JSON Schema Tool.

After generating the JSON Schema, we can then use this schema to generate code when we implement our API. The schema is also useful as formal documentation for our API’s clients, as they can generate client code that uses our API resources. The following listing contains the schema for our API’s resources.

{
    "$schema": "http://json-schema.org/draft-07/schema",
    "$id": "http://example.com/example.json",
    "type": "object",
    "title": "The root schema",
    "description": "The root schema comprises the entire JSON document.",
    "default": {},
    "examples": [
        {
            "neighborhoods": [
                {
                    "name": "Laurel",
                    "zip": "21702",
                    "rentals": [
                        {
                            "bedrooms": "3",
                            "rent": "1500"
                        },
                        {
                            "bedrooms": "2",
                            "rent": "700"
                        },
                        {
                            "bedrooms": "1",
                            "rent": "200"
                        }
                    ]
                },
                {
                    "name": "Dundalk",
                    "zip": "21704",
                    "rentals": [
                        {
                            "bedrooms": "5",
                            "rent": "1500"
                        },
                        {
                            "bedrooms": "1",
                            "rent": "500"
                        },
                        {
                            "bedrooms": "3",
                            "rent": "1200"
                        }
                    ]
                }
            ]
        }
    ],
    "required": [
        "neighborhoods"
    ],
    "additionalProperties": true,
    "properties": {
        "neighborhoods": {
            "$id": "#/properties/neighborhoods",
            "type": "array",
            "title": "The neighborhoods schema",
            "description": "An explanation about the purpose of this instance.",
            "default": [],
            "examples": [
                [
                    {
                        "name": "Laurel",
                        "zip": "21702",
                        "rentals": [
                            {
                                "bedrooms": "3",
                                "rent": "1500"
                            },
                            {
                                "bedrooms": "2",
                                "rent": "700"
                            },
                            {
                                "bedrooms": "1",
                                "rent": "200"
                            }
                        ]
                    },
                    {
                        "name": "Dundalk",
                        "zip": "21704",
                        "rentals": [
                            {
                                "bedrooms": "5",
                                "rent": "1500"
                            },
                            {
                                "bedrooms": "1",
                                "rent": "500"
                            },
                            {
                                "bedrooms": "3",
                                "rent": "1200"
                            }
                        ]
                    }
                ]
            ],
            "additionalItems": true,
            "items": {
                "anyOf": [
                    {
                        "$id": "#/properties/neighborhoods/items/anyOf/0",
                        "type": "object",
                        "title": "The first anyOf schema",
                        "description": "An explanation about the purpose of this instance.",
                        "default": {},
                        "examples": [
                            {
                                "name": "Laurel",
                                "zip": "21702",
                                "rentals": [
                                    {
                                        "bedrooms": "3",
                                        "rent": "1500"
                                    },
                                    {
                                        "bedrooms": "2",
                                        "rent": "700"
                                    },
                                    {
                                        "bedrooms": "1",
                                        "rent": "200"
                                    }
                                ]
                            }
                        ],
                        "required": [
                            "name",
                            "zip",
                            "rentals"
                        ],
                        "additionalProperties": true,
                        "properties": {
                            "name": {
                                "$id": "#/properties/neighborhoods/items/anyOf/0/properties/name",
                                "type": "string",
                                "title": "The name schema",
                                "description": "An explanation about the purpose of this instance.",
                                "default": "",
                                "examples": [
                                    "Laurel"
                                ]
                            },
                            "zip": {
                                "$id": "#/properties/neighborhoods/items/anyOf/0/properties/zip",
                                "type": "string",
                                "title": "The zip schema",
                                "description": "An explanation about the purpose of this instance.",
                                "default": "",
                                "examples": [
                                    "21702"
                                ]
                            },
                            "rentals": {
                                "$id": "#/properties/neighborhoods/items/anyOf/0/properties/rentals",
                                "type": "array",
                                "title": "The rentals schema",
                                "description": "An explanation about the purpose of this instance.",
                                "default": [],
                                "examples": [
                                    [
                                        {
                                            "bedrooms": "3",
                                            "rent": "1500"
                                        },
                                        {
                                            "bedrooms": "2",
                                            "rent": "700"
                                        }
                                    ]
                                ],
                                "additionalItems": true,
                                "items": {
                                    "anyOf": [
                                        {
                                            "$id": "#/properties/neighborhoods/items/anyOf/0/properties/rentals/items/anyOf/0",
                                            "type": "object",
                                            "title": "The first anyOf schema",
                                            "description": "An explanation about the purpose of this instance.",
                                            "default": {},
                                            "examples": [
                                                {
                                                    "bedrooms": "3",
                                                    "rent": "1500"
                                                }
                                            ],
                                            "required": [
                                                "bedrooms",
                                                "rent"
                                            ],
                                            "additionalProperties": true,
                                            "properties": {
                                                "bedrooms": {
                                                    "$id": "#/properties/neighborhoods/items/anyOf/0/properties/rentals/items/anyOf/0/properties/bedrooms",
                                                    "type": "string",
                                                    "title": "The bedrooms schema",
                                                    "description": "An explanation about the purpose of this instance.",
                                                    "default": "",
                                                    "examples": [
                                                        "3"
                                                    ]
                                                },
                                                "rent": {
                                                    "$id": "#/properties/neighborhoods/items/anyOf/0/properties/rentals/items/anyOf/0/properties/rent",
                                                    "type": "string",
                                                    "title": "The rent schema",
                                                    "description": "An explanation about the purpose of this instance.",
                                                    "default": "",
                                                    "examples": [
                                                        "1500"
                                                    ]
                                                }
                                            }
                                        }
                                    ],
                                    "$id": "#/properties/neighborhoods/items/anyOf/0/properties/rentals/items"
                                }
                            }
                        }
                    }
                ],
                "$id": "#/properties/neighborhoods/items"
            }
        }
    }
}

Although considered optional, and usually skipped by developers in a hurry, I feel a JSON schema is essential to defining a robust API. The schema serves the same purpose yesteryear’s XML schema – it is a contract between provider and consumer. Moreover, as you will see when we discuss implementing our API, a schema allows tools to auto-generate our resources as objects in the language of our choice.

Now that we have defined our API resources let’s define the API endpoints.

• JSON-Schema.org is the definitive resource on JSON schemas.

Step Four – Define Endpoints

A REST API is limited to using Hypertext Transfer Protocol (HTTP), where resources are located via their URL, and the actions taken upon the resource are limited to one of the HTTP request methods. Before defining our API endpoints, let’s consider the HTTP methods you will most commonly use when defining a REST API.

HTTP Methods

The most commonly used HTTP methods are the following,

• GET – Retrieve a resource,
• POST – Create a new resource,
• PATCH – modify an existing resource,
• PUT – fully replace an existing resource, and
• DELETE – delete a resource.

The HTTP methods define the actions that can be used to manipulate an APIs resources and dramatically simplifies a REST API, as the API’s “methods” are limited to the HTTP methods.

For more information on the HTTP Methods, a good starting point is Wikipedia’s page on HTTP. The following references contain more detail on the HTTP methods.

• Detailed information on the Hypertext Transfer Protocol (Wikipedia Hypertext Transfer Protocol).
• w3schools.com page on the HTTP Request Methods.
• REST API Tutorial (HTTP Methods).
• Using HTTP Methods for RESTful Services.

REST Anti-pattern (RPC)

One important point to remember when creating a RESTful API is to limit the actions taken on resources to one of the HTTP request methods. Do not turn a RESTful API into an API based around remote procedure calls (RPC). The following illustrates a REST API that is actually an RPC API.

Notice that the URLs no longer represent a resource, they represent an action taken upon a resource. A genuinely RESTful API should only represent resources using the URL and HTTP request methods as the action taken upon those resources. For example, the following illustrates the previous RPC statements modified to be RESTful statements.

When defining your endpoints, do not turn the URLs into RPC statements. An RPC-style “RESTful API” is harder for developers of external systems to understand and makes your API harder to maintain.

Here are a couple of references if you wish to read more on REST compared to RPC and REST anti-patterns.

• Understanding RPC Vs. REST for HTTP APIs
• REST Anti-Patterns

Again, do not turn your REST API into an RPC API that happens to use HTTP as the protocol. It might seem tempting, and lots of organizations do it (heck, I’ve done it in the past I’m ashamed to admit), but then lots of people make unwise choices daily – just don’t do it. REST is not RPC.

• When designing a RESTFUL API, only use the available HTTP methods as the “procedure calls.” URLs are an “address” to a resource and should never describe an action taken upon a resource.

Now that we have discussed the HTTP request methods we are limited to, let’s return to the API interactions we defined through our use-case model above.

API Interactions

By referring to our use-case model, we can construct the following list of requirements/interactions.

• View a rental by MLS number.
• View a neighborhood by Zip Code.
• View neighborhoods.
• View all rentals.
• View all rentals in a neighborhood.
• View all rentals by a price range and/or by bedrooms.
• View all rentals in a particular neighborhood by price range and/or bedroom range.

We can now use these interactions to define the API endpoints.

REST Endpoints

Refer to the interaction list in the previous section and construct a list of our API’s endpoints and the HTTP method used to perform those interactions. The URL (the address to the resource) and the HTTP method (the action taken upon the resource) together define the API.

The URLs are the resource address, while the action is the HTTP method. Of course, in our simplified API, all our interactions are “viewing” resources and so all use the GET HTTP request method.

Step Five – Implement Endpoints

After defining our API, we implement the API using the desired programming language. Most programming languages offer REST frameworks that simplify writing your API. For instance, if your language of choice is Python, then the Flask Web framework is a good choice. If using Node.js, then consider Express.js. If using Java, then use an implementation of the Java API for Restful Web Services (JAX-RS) specification. There are also other languages you might use, such as ASP.NET or Ruby. The RapidAPI website has many tutorials explaining in detail how to implement a RESTful API using the language of choice. The following are good tutorials to learn how to implement a RESTful API using various programming languages.

• How to Build an API in Python (with Flask & RapidAPI).
• How to Build a RESTful API in Node.js (with Express.js).
• Top 10 Best Java REST and Microservice Frameworks (2020).
• How to Build a Java RESTful API with Spring Boot.
• How to Create Your Own RESTful API (20+ Tutorials by Programming Language).

Endpoints – Implementation Architecture

However, there are some underlying principles for robustly implementing a RESTful API. Use a layered, or tiered, architecture. Rather than integrating an API into an application, ensure it is distinct and isolated from the underlying system. Stand up a webserver if needed, and host your API and it’s underlying application on that server, but do not modify your application to include a REST API. When developing the API as a distinct application, have it communicate with the underlying system to modify that system’s resources.

• Expose an existing system through a REST API only. Maintain a clear delineation between the system implementing a REST API and the underlying application.

The following diagram illustrates a well-designed RESTful API.

API Consumers communicate with a REST API using HTTP methods via the API’s REST endpoints. The REST API is a separate application from the underlying system. The REST API communicates with the underlying system but is not integrated into that underlying system. This distinction is a critical architectural principle when adding a REST API to an existing system.

Here are some excellent resources for learning more about RESTful APIs and how to design them.

• Comparing Web APIs with service-oriented architecture and enterprise application integration.
• Building an Enterprise API Program.
• API vs. Web Service: What’s the Difference?

Rental Listing Example – Implementation

The RESTful API code contains code specific to receiving HTTP requests and returning responses. For example, the following code is a Java class that implements the REST endpoints and resources identified earlier in this tutorial. Here we are using the JAX-RS framework and annotations to define the endpoints. Although the methods return Java classes, behind the scenes, the Jackson Java JSON library converts the objects to their JSON equivalents. Frameworks in other languages should have similar object/JSON translation capabilities.

package com.tutorial.rentalsareus.PropertyListing;

import java.util.List;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import org.springframework.stereotype.Component;
import io.swagger.annotations.Api;

@Component
@Path("/propertylisting")
@Produces("application/json")
@Api(value = "PropertyListing Resource", produces = "application/json")
public class PropertyListingController {

  // get all neighborhoods
  @GET
  @Path("/neighborhoods") 
  public List<Neighborhood> getNeighborhoods(){return null;}
  
  // get all rentals
  @GET
  @Path("/neighborhoods/rentals")
  public List<Rental> getRentals() {return null;}
  
  // get a specific neighborhood by zip-code
  @GET
  @Path("/neighborhoods/{zip-code}")
  public Neighborhood getNeighborhood(@PathParam("zip-code") String zipCode) {return null;}
 
  
  // get all rentals in a neighborhood specified by zip-code
  @GET
  @Path("/neigborhoods/{zip-code}/rentals")
  public List<Rental> getRentalsForNeighborhood(@PathParam("zip-code") String zipCode) {return null;}
 
  // get a specific rental by mls
  @GET
  @Path("/neighborhoods/rentals/{mls}")
  public Rental getRental(@PathParam("mls") String mls) {return null;}
  
  
  // get all rentals within a price range
  @GET
  @Path("/neighborhoods/rentals")
  public List<Rental> getRentalsByPrice(@QueryParam("min-price") String minPrice, 
    @QueryParam("max-price") String maxPrice) {return null;}

  // get all rentals within a price range 
  @GET
  @Path("/neighborhoods/rentals")
  public List<Rental> getRentalsByBedrooms(@QueryParam("min-bedrooms") String minRooms) {return null;} 
    
  @GET
  @Path("/neighborhoods/{zip-code}/rentals")
  public List<Rental> getRentalsByPriceAndNeigborhood(@PathParam("zip-code") String zipCode, 
    @QueryParam("min-price") String minPrice, @QueryParam("max-price") String maxPrice) {return null;}

  @GET
  @Path("/neighborhoods/{zip-code}/rentals")
  public List<Rental> getRentalsByBedroomsAndNeighborhood(@PathParam("zip-code") String zipCode, 
    @QueryParam("min-bedrooms") String minRooms) {return null;} 
   
  
}

Recall, that earlier we defined a REST schema for our resources. We can use a tool such as jsonschema2pojo to generate Java classes from our schema.

For example, here we are creating a Neighborhood and a Rental object from our schema. And, as we saw in the previous code listing, these are the classes our API returns (of course translated to JSON).

Although the analysis is Java-specific, most languages will work similarly. Implementing a REST API entails implementing the resources as objects in the language being used, implementing the endpoints as methods in the language being used, and using a library that translates between JSON and programming language objects.

• The proper terminology for the translation between JSON/programming-object is serialize/deserialize. JSON is deserialized into a programming language object and a programming language object is serialized into JSON.

As this is not a language-specific tutorial, we do not fully implement the application. If you wish to see a fully implemented example, refer to the tutorial How to Build a Java RESTful API with Spring Boot.

Step Six – Document Your API

An important, but often overlooked step in implementing your REST API is to document it. Documentation, though usually not a developer’s favorite activity, is essential. Documentation is what makes your API usable to developers that develop client applications that use your API. Consider this, if given a choice between two equivalent APIs and only one of which is documented, which API would you choose?  Document your API.

Defining a JSON schema, as we did above, is arguably the best documentation we can provide. As already illustrated, by providing a JSON schema, clients of our API can quickly generate client code in the language of their choice. But you should also create human-readable documentation.

Many tools exist to document your API. If using Java, Swagger is arguable the best solution to automate documenting your API (swagger.io). However, even if you do not select an automated tool, you should provide some documentation for your API.

• The following resource is an excellent resource for learning how to document an API (API Documentation Guide & Documentation Tutorials).
• How to Build a Java RESTful API with Spring Boot documents the created API using Swagger.

Document your API so that others can more easily use the API.

Step Seven – Publish Your API

As a final step, consider publishing your API to an API clearinghouse available on the web. RapidAPI is one such clearinghouse and provides a powerful, yet easy to use, platform for publishing an API. By publishing your API using RapidAPI, it is readily available to RapidAPI’s broad userbase. It will translate into more users, and if your API is monetized, more revenue, as you will have more users.

• RapidAPI Documentation.
• The tutorials found in this resource all contain sections on how to publish an API to RapidAPI (How to Create Your Own RESTful API 20+ Tutorials by Programming Language).

Conclusion

Creating a RESTful API that users will enjoy using involves more than coding. It also involves carefully planning and designing your API. When exposing an existing API, the steps discussed in this tutorial will help create a better-crafted API that users will delight in using. And publishing your API on RapidAPI will make your API more readily available to consumers that otherwise might not know about your API. Regardless of the programming language used, the steps outlined in this tutorial are essential to crafting a robust API.

Consider this tutorial as a starting point for further reading. The discussion here was broad, and there is much more detail to designing and implementing a RESTful API. A more detailed example of using JAX-RS to implement a RESTful API is provided by the following article, also written by myself. It covers most of the concepts presented in this article; however, it gives much more implementation details (How to Build a Java RESTful API with Spring Boot). Or, simply navigate around RapidAPI’s blog (Last Call), which contains countless articles and tutorials to help you craft your API.