Skip to main content
Redhat Developers  Logo
  • Products

    Featured

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat OpenShift AI
      Red Hat OpenShift AI
    • Red Hat Enterprise Linux AI
      Linux icon inside of a brain
    • Image mode for Red Hat Enterprise Linux
      RHEL image mode
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • Red Hat Developer Hub
      Developer Hub
    • View All Red Hat Products
    • Linux

      • Red Hat Enterprise Linux
      • Image mode for Red Hat Enterprise Linux
      • Red Hat Universal Base Images (UBI)
    • Java runtimes & frameworks

      • JBoss Enterprise Application Platform
      • Red Hat build of OpenJDK
    • Kubernetes

      • Red Hat OpenShift
      • Microsoft Azure Red Hat OpenShift
      • Red Hat OpenShift Virtualization
      • Red Hat OpenShift Lightspeed
    • Integration & App Connectivity

      • Red Hat Build of Apache Camel
      • Red Hat Service Interconnect
      • Red Hat Connectivity Link
    • AI/ML

      • Red Hat OpenShift AI
      • Red Hat Enterprise Linux AI
    • Automation

      • Red Hat Ansible Automation Platform
      • Red Hat Ansible Lightspeed
    • Developer tools

      • Red Hat Trusted Software Supply Chain
      • Podman Desktop
      • Red Hat OpenShift Dev Spaces
    • Developer Sandbox

      Developer Sandbox
      Try Red Hat products and technologies without setup or configuration fees for 30 days with this shared Openshift and Kubernetes cluster.
    • Try at no cost
  • Technologies

    Featured

    • AI/ML
      AI/ML Icon
    • Linux
      Linux Icon
    • Kubernetes
      Cloud icon
    • Automation
      Automation Icon showing arrows moving in a circle around a gear
    • View All Technologies
    • Programming Languages & Frameworks

      • Java
      • Python
      • JavaScript
    • System Design & Architecture

      • Red Hat architecture and design patterns
      • Microservices
      • Event-Driven Architecture
      • Databases
    • Developer Productivity

      • Developer productivity
      • Developer Tools
      • GitOps
    • Secure Development & Architectures

      • Security
      • Secure coding
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
      • View All Technologies
    • Start exploring in the Developer Sandbox for free

      sandbox graphic
      Try Red Hat's products and technologies without setup or configuration.
    • Try at no cost
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud icon
    • Java
      Java icon
    • AI/ML
      AI/ML Icon
    • View All Learning Resources

    E-Books

    • GitOps Cookbook
    • Podman in Action
    • Kubernetes Operators
    • The Path to GitOps
    • View All E-books

    Cheat Sheets

    • Linux Commands
    • Bash Commands
    • Git
    • systemd Commands
    • View All Cheat Sheets

    Documentation

    • API Catalog
    • Product Documentation
    • Legacy Documentation
    • Red Hat Learning

      Learning image
      Boost your technical skills to expert-level with the help of interactive lessons offered by various Red Hat Learning programs.
    • Explore Red Hat Learning
  • Developer Sandbox

    Developer Sandbox

    • Access Red Hat’s products and technologies without setup or configuration, and start developing quicker than ever before with our new, no-cost sandbox environments.
    • Explore Developer Sandbox

    Featured Developer Sandbox activities

    • Get started with your Developer Sandbox
    • OpenShift virtualization and application modernization using the Developer Sandbox
    • Explore all Developer Sandbox activities

    Ready to start developing apps?

    • Try at no cost
  • Blog
  • Events
  • Videos

Know how RESTful your API is: An Overview of the Richardson Maturity Model

September 13, 2017
Rahul Kumar
Related topics:
Java
Related products:
Red Hat Enterprise Linux

Share:

    Most of the time, I see developers are bit confused about the term REST. For some enterprise application developers, the meaning of REST is JSON i.e. if they are using JSON in their application, which means they working on REST API, which is not true to some extent. Let's take a look what exactly a REST API is.

    Let's say we designed a REST API. How do we know how much Restful API is? Some developers call it "Not Restful API", some call it "Partially Restful API", for some, it is "Fully Restful API", and for some "It is not REST API at all or they call it SOAP based web service". Imagine it as a spectrum from Not Restful to Fully Restful API. To know at which level API stand, Richardson introduces a model called Richardson Maturity Model. As the name itself suggests, it tells about the maturity level of REST API.

    According to the Richardson Maturity Model, any REST API belongs to any of the maturity levels from Level 0 to Level 3, mentioned below.

     

    It's not necessary that every REST API developed should be as high as Level 3. But this model helps the developers of REST API to know at which Level their API belongs to and how can they make their API better by moving up in the above model hierarchy.

    Level 0: The Swamp of POX

    1. API designed at this level are not at all Rest APIs and This is where SOAP based web services takes place.
    2. At this Level,There is no concept of Resource Based URI, Hypermedia, and no proper use of HTTP Protocol (which are key characteristics of a REST API). In fact, the API, which belongs to this Level, does not make use or leverages the full potential of the HTTP protocol. HTTP is merely treated as a Transport Layer protocol or just a Tunneling Mechanism between Client and Server.

    Example: Let's look at a twitter API that allows the users to create a tweet, comment on a tweet, follow the user, share the tweets, etc. A sample URI or End Point for such twitter API designed at Level 0 can be http://<hostname>:<port>/twitter.

    Here's how the Endpoint at the server side will know what to do with an incoming request from the Client or what operations to perform like create a tweet, delete a tweet, or comment on a tweet etc. Also, how can an API Client tell the Service Endpoint to do different operations?

    In SOAP-Based web services, this is done by sending a message or request body, which is sent to the endpoint via SOAP protocol. The Request Body essentially contains all information about the operation (like DELETE tweet, CREATE tweet, Update tweet etc.) and data on which the operation is performed, e.g. for creating a tweet , the Request body may be something like:

    Similarly for deleting a tweet, Request Body may <delete-tweet>...</delete-tweet>. If there is some error in creating a tweet, probably we will have a response like <create-tweet-error>Error cause</create-tweet-error> from the server.

    Notice that all these requests go to a single endpoint and that's how the endpoint knows how to do different operations. Since Request body itself identifies what kind of operation needs to be performed, it makes sense to use single URI for all operations. Or we can say that the same http method can be used for each operation on tweet because all the details about the operation are carried in the Request Body (called SOAP XML also) and we are not leveraging the potential of HTTP Methods/Verbs. As HTTP is used just as a tunnel between the client and server at this Level.

    This is called swamp of POX (plain old XML) approach. So, everything is defined by XML in the case of SOAP web service and that is called POX(Plain Old XML).

    LEVEL 1: Resource BASED ADDRESS/URI

    1. This is a starting Level for a REST API. In this Level, the Concept of Resource-based Address is introduced, which tells you there should be Individual URI for each Resource on the server (unlike LEVEL 0 where we have a single URI for each incoming request from Client).
    2. It's like reducing the burden from the single endpoint (LEVEL 0 end Point which handles all operations) into multiple Resource Based URIs like Divide and Conquer algorithm.
      Example: Create tweet request going to URI1, delete tweet Request is going to URI2 etc. So whether we create a new tweet, delete the tweet, or we update the tweet, the operation information (create, update, delete of tweet) is still in the Request body. In the above twitter API, we can think TWEET, COMMENT, and FOLLOWER as different resources in above application.
    3. If we just designed Resource-based URI and nothing else, then we are at LEVEL 1 of the maturity model. In this, the HTTP is just used as a tunnel between client and server and we have not leveraged the potential of HTTP as an application Layer Protocol.
    4. Most of the developers who are beginners for REST design REST API at this LEVEL.
    5.  

    LEVEL 2: Utilize Potential of HTTP as Application Layer Protocol

    1. REST developed under this level leverages the full potential of HTTP as an application Layer Protocol.
    2. REST API developed at this LEVEL uses Standard HTTP methods/verbs and different HTTP status codes to do different operations on Resource URI. So, the Request Body will no longer carry Operation information at this level. Hence, this API is much more mature than the API developed at LEVEL 0 and LEVEL 1.

    Example: Let's say we want to create a tweet and decide later we want to delete it. So we will have Resource "Tweet" and we can form resource based URI like http://<host name>:<port>/api/tweets. Now, how to tell this single resource based URI to do different operations and the answer is using HTTP verbs like below.

    A sample Post request for creating a tweet is as below

    A sample Delete Request for deleting a tweet at server side.

    In this example, we observe both requests are going to single Resource Based Address and Operations is not managed by Request Body anymore and we make use of HTTP methods to perform different operations on the same URI and Request Body merely carrying raw data on which the operation will be performed at the server side.We are making use of proper status codes also so that it can be helpful for a client that whether the operation is successful or not.

    LEVEL 3: Use Hypermedia or HATEOAS

    1. In LEVEL 1, the Resource-Based URI concept is introduced and in LEVEL 2, we leveraged the full potential of HTTP protocol using HTTP methods. LEVEL 3 makes use of Hypermedia (also Called HATEOAS--Hypermedia as Engine of Application state in REST world), which drives the interaction for the API Client. Generally, the API Client is not aware of all resource endpoints and REST does not deal much with API documents (which can tell API client information about all endpoints), unlike SOAP where we have WSDL, which provides information about service to the API Client.
    2. Different Resource Based Endpoints are made aware to API Client using concept HATEOAS i.e. sending some hypermedia as the response of endpoint response which in turns acts as Engine of Application state and hence the name HATEOAS. The HATEOAS concept in REST API makes API self-documented and hence no need for API documentation.
    3. API developed at this LEVEL 3 is generally considered as fully RESTful API and this is where we see the charm of REST API.

    Example: Let's say the API Client wants to get all the tweets available in the Server and the list of comments on a particular tweet. To get this information, the Client should be aware of both the endpoints and URI performing their tasks respectively.

    If we observe the above example carefully, once the client makes an HTTP GET request to /tweets endpoint, the Client gets all the tweets in the server along with some extra information, which conveys to the Client. In that case, it wants to get all comments on a tweet, use the endpoint sent in response, which is nothing but the concept of Hypermedia in Rest world. So now the Client does not need to know the endpoint to get all comments on a tweet, in fact, the API itself is telling the client to use the endpoint, which is sent in response. So Hypermedia in response is driving the application state and that's why the name HATEOAS(Hypermedia as Engine of Application State).

    Conclusion: 

    1. This model simplifies the process of developing REST API and help developers how can they design a mature Restful API. REST is a term first coined by Roy Fielding. Most of the concept of REST is inspired by HTTP protocol specification whose author is also Roy Fielding and hence there should not be much surprise that REST leverages the full potential of HTTP Specifications. Using HTTP Protocol just a data transport media(i.e Transport layer) between client and server is not recommended while designing REST API. Since HTTP lets you customize the behavior of server-side application using its specifications(like HTTP methods, HTTP status codes, Content-type etc.), one should make complete use of it and that's where we see actual benefit of HTTP as application layer protocol in REST API.
    2. Also, one important aspect to notice here is that making use of JSON media type, as HTTP exchange between client and server does not guarantee that you are dealing with REST API. JSON is merely most preferred MEDIA TYPE in REST World because JSON is considered to be less verbose from other MEDIA TYPES like XML, XHTML, PLAINTEXT etc. and JSON objects are easily understood by any web client (e.g. In case we are dealing with an application, which displays REST API data in form of UI, then JSON  media type can be the best choice in that application because browser/web-client can easily understand JSON objects).
    3. In short, A Restful API implementation at server side must be like below:
      REST = RESOURCE BASED URI+ Full Utilization of HTTP Specification+Hypermedia (or   HATEOAS)
    4. The most preferred API for developing Rest API is JAX-RS( As part of JEE specification) and Spring BOOT (An open source third Party Framework).
    5. Note that before going through this article, sound knowledge of HTTP and REST Architecture is necessary.

    To learn about Red Hat Openshift Container Platform, allowing you to provision, manage, and scale container-based applications.

    Last updated: June 8, 2021

    Recent Posts

    • Meet the Red Hat Node.js team at PowerUP 2025

    • How to use pipelines for AI/ML automation at the edge

    • What's new in network observability 1.8

    • LLM Compressor: Optimize LLMs for low-latency deployments

    • How to set up NVIDIA NIM on Red Hat OpenShift AI

    Red Hat Developers logo LinkedIn YouTube Twitter Facebook

    Products

    • Red Hat Enterprise Linux
    • Red Hat OpenShift
    • Red Hat Ansible Automation Platform

    Build

    • Developer Sandbox
    • Developer Tools
    • Interactive Tutorials
    • API Catalog

    Quicklinks

    • Learning Resources
    • E-books
    • Cheat Sheets
    • Blog
    • Events
    • Newsletter

    Communicate

    • About us
    • Contact sales
    • Find a partner
    • Report a website issue
    • Site Status Dashboard
    • Report a security problem

    RED HAT DEVELOPER

    Build here. Go anywhere.

    We serve the builders. The problem solvers who create careers with code.

    Join us if you’re a developer, software engineer, web designer, front-end designer, UX designer, computer scientist, architect, tester, product manager, project manager or team lead.

    Sign me up

    Red Hat legal and privacy links

    • About Red Hat
    • Jobs
    • Events
    • Locations
    • Contact Red Hat
    • Red Hat Blog
    • Inclusion at Red Hat
    • Cool Stuff Store
    • Red Hat Summit

    Red Hat legal and privacy links

    • Privacy statement
    • Terms of use
    • All policies and guidelines
    • Digital accessibility

    Report a website issue