Mastering RESTful Web Services with Java E-Book

Marián Varga

• Herausgeber: Packt Publishing
• Kategorie: Wissenschaft und neue Technologien
• Sprache: Englisch

Seitenzahl: 523

Veröffentlichungsjahr: 2025

Beschreibung

REST powers the modern web, yet developers grapple with architectural missteps that lead to poorly designed REST endpoints, inadequate error handling, security vulnerabilities, and maintenance headaches. Written by five software engineering and Java experts, Mastering RESTful Web Services with Java helps you overcome these pitfalls with a deep, practical understanding of REST architecture, HTTP protocols, and modern API design principles.
This hands-on guide introduces foundational concepts based on Roy Fielding’s principles and the Richardson Maturity Model and shows you how to apply them in your API development projects. You’ll build a Product API from scratch, progressively enhancing it with documentation, versioning, and security features, and then advance to creating an Order Management API that interacts with the Product API, while implementing advanced testing and performance optimization techniques. Each chapter delivers step-by-step explanations and practical examples, ensuring you develop production-ready skills that translate directly to your daily work.
By the end of the book, you’ll be ready to deliver production-grade RESTful services and become the API expert your team turns to for critical application development projects.

Leseprobe

Mastering RESTful Web Services with Java

Practical guide for building secure and scalable production-ready REST APIs

Marián Varga

Pedro Henrique Pereira de Andrade

Silvio de Morais

Thiago Bomfim

Igor Avancini Fraga

Mastering RESTful Web Services with Java

Copyright © 2025 Packt Publishing

All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews.

Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the authors, nor Packt Publishing or its dealers and distributors, will be held liable for any damages caused or alleged to have been caused directly or indirectly by this book.

Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.

Portfolio Director: Ashwin Nair

Relationship Lead: Sneha Shinde

Project Manager: Ruvika Rao

Content Engineer: Roshan Ravi Kumar

Technical Editor: Sweety Pagaria

Copy Editor: Safis Editing

Proofreader: Roshan Ravi Kumar

Indexer: Pratik Shirodkar

Production Designer: Jyoti Kadam

Growth Lead: Anamika Singh

First published: July 2025

Production reference: 1090725

Published by Packt Publishing Ltd.

Grosvenor House

11 St Paul’s Square

Birmingham

B3 1RB, UK.

ISBN 978-1-83546-610-0

www.packtpub.com

Contributors

About the authors

Marián Varga has dedicated his career to the integration and API aspects of software solutions across diverse industries. His extensive experience has given him a front-row seat to the evolution of various API styles, their implementation possibilities, and the challenges they present. Passionate about connecting systems through APIs and integration solutions, Marián also bridges the gap between business and technical people, enhancing the efficiency and enjoyment of software development. Marián creates content for and builds a community of people interested in integration at love2integrate.com.

Pedro Henrique Pereira de Andrade has over 14 years of hands-on experience as a software engineer, specializing in ERP systems for small to medium-sized companies across diverse industries. Over the past six years, he has transitioned to larger projects in various countries for different domains, showcasing his adaptability and expertise in using Java technologies such as the Spring Framework for web applications.

As a co-founder of BarreirasJUG, a Java User Group in Brazil, Andrade has actively contributed to the Java community, fostering collaboration and knowledge sharing.

Silvio de Morais is a software architect from Porto Alegre, Brazil, with over 30 years of experience in IT and software development. He has led projects for Fortune 500 companies, focusing on digital transformation, cloud computing, and software architecture. Silvio holds degrees from PUC Brazil and Harvard University and has conducted research at the University of Tokyo. He actively contributes to tech forums, conferences, and Java User Groups, promoting continuous improvement. He now lives in Orlando, FL, with his wife.

Thiago Bomfim has many years of experience in developing Java web applications. He has worked in start-ups and large companies, where he has had the opportunity to create REST APIs for all types of clients, including desktop, web, backend, and mobile. His career is fueled by a deep commitment to engineering excellence, following the best practices of RESTful APIs and focusing on high performance and backward compatibility. Beyond coding, Thiago is passionate about sharing knowledge. He writes technical articles on his blog, speaks at events, mentors developers, and co-hosts the Out of The Box Developer podcast.

Igor Avancini Fraga possesses over 12 years of experience in software engineering and is a full member of the Java Community Process (JCP) by Oracle. He has diligently worked on developing applications, services, and features using Java, C#, and X++ for various companies in Brazil and the United States, thereby delivering numerous successful projects throughout his career, encompassing both backend and frontend domains. In recent years, his focus has predominantly been on backend development tailored for the cloud, with a particular emphasis on the development of RESTful APIs and their seamless integration with other services, third-party platforms, and, more recently, AI technologies.

About the reviewers

Mohamed Abdou, a skilled software engineer at Amazon UK, is a contributor to artificial general intelligence. His career reflects technical acumen and passion for impactful software solutions. Mohamed’s extensive experience covers large-scale systems, software engineering, AI/ML, and cybersecurity. He has a strong academic background and significant hands-on experience in building complex software and APIs, including open source contributions used by millions and a technical book benefiting many developers. He offers valuable practical knowledge and a unique perspective on modern development. His expertise in secure coding, agile methods, technical leadership, mentoring, and problem-solving highlights his capabilities as a seasoned professional.

Felipe Alexandre Oliveira is a seasoned backend developer with over 11 years of experience in software engineering. He has contributed to the development of high-traffic systems and applications with complex business logic, consistently delivering scalable and maintainable solutions. His technical expertise spans object-oriented programming (OOP), data structures, Java, Spring, test-driven development (TDD), AWS, and Docker.

Felipe has a strong interest in application scalability, cloud architecture, and software development best practices. He is passionate about technology and thrives on the challenge of turning real-world problems into effective, user-focused solutions.

Preface

This book is a practical guide to designing, building, documenting, testing, and deploying RESTful APIs using modern Java frameworks. REST APIs have become a standard way of enabling communication between systems, especially in microservices and other distributed architectures. With Java being one of the most widely used languages for backend development, understanding how to build effective APIs with Java is a key skill for today’s developers.

Throughout the chapters, you’ll explore hands-on techniques using Spring Boot, OpenAPI, and other popular tools and libraries. You’ll also gain exposure to containerization, observability, API security, and performance tuning – everything you need to create robust, scalable, and maintainable APIs. Whether you’re working in a start-up or an enterprise, the skills covered here will help you deliver high-quality backend services that meet modern development standards.

Who this book is for

This book is ideal for backend Java developers with a few years of experience who are looking to improve the design, performance, and scalability of their REST APIs. It’s also a valuable resource for tech leads and software architects involved in designing distributed systems.

What this book covers

Chapter 1, Understanding RESTful Core Concepts, introduces the foundational principles of REST architecture and explains the different maturity levels of RESTful APIs. It also covers the role of JSON as a standard data format, outlines practical guidelines for designing effective APIs, and explores common use cases where REST is applied in real-world systems.

Chapter 2, Exposing a RESTful API with Spring, focuses on designing and implementing a RESTful API using Spring Boot. You’ll begin by designing a simple Product API, then move on to building it step by step with Spring Boot, one of the most popular frameworks for Java-based web applications. This chapter provides hands-on experience in turning REST concepts into a working API.

Chapter 3, Documenting Your API Effectively,explores the importance of clear and accurate API documentation in building reliable and maintainable services. You’ll learn how to use OpenAPI to standardize your API documentation and understand the differences between specification-first and code-first approaches. The chapter also walks you through documenting the Product API introduced earlier, ensuring it is both understandable and usable by other developers and systems.

Chapter 4, Generating Code from OpenAPI, guides you through creating a full API based on an OpenAPI specification. You’ll start by defining the Order Management API specification, then generate the necessary code to jumpstart development. The chapter also covers organizing the project’s package structure, implementing the API controller, and integrating the Order Management API and the Product API introduced earlier.

Chapter 5, Managing API Evolution, shows how to handle changes and updates to your APIs without disrupting existing users. You’ll learn about different versioning strategies, see how to implement versioning in the Product API, and explore best practices for managing API evolution to ensure your services remain reliable and backwards compatible.

Chapter 6, Advanced API Concepts and Implementations, dives into key techniques for building robust and user-friendly APIs. You’ll explore advanced data handling methods such as pagination, filtering, and file upload/download through REST APIs. The chapter also covers HATEOAS to improve API navigation and introduces resilience patterns to make your APIs more reliable and fault-tolerant in real-world scenarios.

Chapter 7, Securing Your RESTful APIs, focuses on protecting your APIs from unauthorized access and security threats. You’ll learn about authentication and authorization techniques, explore key security principles from OWASP, and understand how to address common vulnerabilities through the management of Common Vulnerabilities and Exposures (CVEs) to keep your APIs safe and trustworthy.

Chapter 8, Testing Strategies for Robust APIs, explores both traditional API testing methods and the exciting impact of generative AI on the testing process. You’ll learn how AI tools such as ChatGPT are transforming test creation, making it faster, smarter, and more effective, while still covering essential testing types, tools, and best practices for building reliable APIs.

Chapter 9, Monitoring and Observability, dives into best practices for logging and tracing in RESTful APIs. You’ll learn how structured logging, correlation IDs, and centralized filters help with effective troubleshooting, while distributed tracing tools such as Micrometer and OpenTelemetry provide deep visibility into service performance and request flows across distributed systems.

Chapter 10, Scaling and Performance Optimization Techniques, covers essential strategies to improve the speed and scalability of RESTful APIs. You’ll learn about performance-focused design, leveraging Java’s virtual threads, using infrastructure effectively, and validating improvements through load testing to ensure your APIs handle growing demands efficiently.

Chapter 11, Alternative Java Frameworks to Build RESTful APIs, provides a high-level overview of popular Java frameworks beyond Spring Boot. You’ll explore the benefits of standardization and the choice between imperative and reactive programming, and learn about Java EE, Jakarta EE, and MicroProfile. The chapter also includes practical examples using Quarkus and Helidon to show how REST principles apply across different tools.

Chapter 12, Deploying APIs, guides you through the essential steps to move your Java RESTful APIs from development to production. You’ll explore deployment preparation, containerization with Docker, and the use of PaaS platforms. This chapter focuses on practical, beginner-friendly workflows that serve as a solid foundation for more advanced DevOps practices in the future.

To get the most out of this book

This book is primarily aimed at backend developers working with, or interested in working with REST APIs. It also benefits architects and tech leads who want to dive deeper into topics like API monitoring, deployment, managing API growth in a healthy way, avoiding breaking changes, and improving resilience and security.

Download the example code files

The code bundle for the book is hosted on GitHub at https://github.com/PacktPublishing/Mastering-RESTful-Web-Services-with-Java. We also have other code bundles from our rich catalog of books and videos available at https://github.com/PacktPublishing. Check them out!

Download the color images

We also provide a PDF file that has color images of the screenshots/diagrams used in this book. You can download it here:.

Conventions used

There are a number of text conventions used throughout this book.

CodeInText: Indicates code words in text, database table names, folder names, filenames, file extensions, pathnames, dummy URLs, user input, and Twitter handles. For example: “To add the Spring Data dependency, include the following entry in your pom.xml file:”.

A block of code is set as follows:

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency>

Any command-line input or output is written as follows:

curl -X 'GET' \

Bold: Indicates a new term, an important word, or words that you see on the screen. For instance, words in menus or dialog boxes appear in the text like this. For example: “To adhere to the Don’t Repeat Yourself (DRY) principle, we must update the code from version 1.”

Warnings or important notes appear like this.

Tips and tricks appear like this.

Get in touch

Feedback from our readers is always welcome.

General feedback: If you have questions about any aspect of this book or have any general feedback, please email us at [email protected] mention the book’s title in the subject of your message.

Errata: Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you have found a mistake in this book, we would be grateful if you reported this to us. Please visit http://www.packt.com/submit-errata, click Submit Errata, and fill in the form.

Piracy: If you come across any illegal copies of our works in any form on the internet, we would be grateful if you would provide us with the location address or website name. Please contact us at [email protected] with a link to the material.

If you are interested in becoming an author: If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, please visit http://authors.packt.com/.

Share your thoughts

Once you’ve read Mastering RESTful Web Services with Java, we’d love to hear your thoughts! Please click here to go straight to the Amazon review page for this book and share your feedback.

Your review is important to us and the tech community and will help us make sure we’re delivering excellent quality content.

Download a free PDF copy of this book

Thanks for purchasing this book!

Do you like to read on the go but are unable to carry your print books everywhere?

Is your eBook purchase not compatible with the device of your choice?

Don’t worry, now with every Packt book you get a DRM-free PDF version of that book at no cost.

Read anywhere, any place, on any device. Search, copy, and paste code from your favorite technical books directly into your application.

The perks don’t stop there, you can get exclusive access to discounts, newsletters, and great free content in your inbox daily.

Follow these simple steps to get the benefits:

Scan the QR code or visit the link below:

https://packt.link/free-ebook/9781835466100

Submit your proof of purchase.That’s it! We’ll send your free PDF and other benefits to your email directly.

Share your thoughts

Once you’ve read Mastering RESTful Web Services with Java, we’d love to hear your thoughts! Scan the QR code below to go straight to the Amazon review page for this book and share your feedback.

https://packt.link/r/1835466109

Your review is important to us and the tech community and will help us make sure we’re delivering excellent quality content.

Part 1

Steps to a Great API

This part lays the foundation for building robust RESTful APIs using Java. It introduces the key concepts of REST architecture, walks through exposing a real-world API with Spring Boot, and covers essential documentation techniques using OpenAPI. You’ll also learn how to generate API code from specifications to streamline development and ensure consistency.

This part will cover the following chapters:

Chapter 1, Understanding RESTful Core ConceptsChapter 2, Exposing a RESTful API with SpringChapter 3, Documenting Your API EffectivelyChapter 4, Generating Code from OpenAPI

2

Exposing a RESTful API with Spring

To implement REST APIs, in most chapters of this book, we are going to use Spring Boot. As it is a well-known and popular framework, it is very likely that you are familiar with it or have used it before.

However, the general API design principles are easily transferable to other Java technologies. You will learn more about how we can apply these principles to other technologies in Chapter 11.

In this chapter, we will discuss the process of designing a RESTful API. We will also concentrate on the practical implementation of the API using the Spring Framework, a popular choice for building RESTful APIs. By the end of this chapter, you will have the knowledge to design and create a RESTful API following the best practices.

In this chapter, we will be covering these topics:

Designing the product APIAPI implementation using Spring Boot

Technical requirements

In this chapter, we will implement an example product API. To be able to follow along and use the code examples as they are printed in the book, you should have the following:

Intermediate knowledge of the Java language and platformAt least a basic knowledge of Spring Boot or a similar frameworkJava 21 and Maven 3.9.0 installedBasic knowledge of a tool for calling REST APIs, such as curl, is recommended

In this chapter, we are going to apply REST principles to create our API; you can access the code for this chapter on GitHub at https://github.com/PacktPublishing/Mastering-RESTful-Web-Services-with-Java/tree/main/chapter2.

Designing the product API

The product API we will develop is an API for managing products. Our API will offer various operations, which will be detailed during the design phase.

Spending an adequate amount of time on properly designing the API before starting to write the code can save a lot of time later, preventing costly and risky refactoring.

The design stage should include the following:

Defining the requirements: Understanding the use cases and who will use the API is essential to creating an API that contains everything that is needed and nothing more. A good understanding of the requirements lets you avoid breaking changes for as long as possible. In Chapter 5, we will talk about how you can evolve your API and ensure backward compatibility.Identifying the resources: Resources are usually domain entities such as users or products. Relationships between multiple entities are often represented by a hierarchical URI structure.Defining the resource structure: After identifying the resources, it is necessary to define the resource fields and relationships.Designing the endpoints: With the resources and the domain defined, the next step is to identify the endpoints that should be exposed, how they should be exposed, and what HTTP methods should be used for what purpose.Error handling: Having clear error responses with standard error codes helps the client to react to the error correctly.Security: It is essential to prevent malicious actors from accessing resources that they are not authorized to. You will learn more about API security in Chapter 7.

An endpoint is a specific URI that enables clients to interact with a server via an API to perform a specific function. It represents an operation that can be executed using a unique path and the corresponding HTTP method.

Based on these design steps, you can proceed directly to implementing the API in code using Java. This is called the code-first approach, usually representing the fastest path to a working API.

A different approach, called specification-first, will be explained in Chapter 3.

Defining the requirements

The API requirements can be divided into functional and non-functional:

Functional requirements: These describe the specific functions and features that the software must perform. Examples include data validation, data processing, and system interactions.Non-functional requirements: These are also known as quality attributes or software quality requirements that specify the qualities or characteristics that the software must possess. Examples include performance (response time and throughput), reliability, security, scalability, usability, and maintainability.

In this chapter, we will only work on the functional requirements. We will get to some of the non-functional requirements in Chapters 7 and 10.

As mentioned earlier, our example REST API will be a product API and will have the following requirements:

Product creation: The API should allow users to create new products by providing necessary information such as the SKU (Stock Keeping Unit, in the context of this book it is the unique product ID), name, description, and priceProduct retrieval: Users should be able to retrieve information about all products available in the systemProduct details: The API should provide endpoints to retrieve detailed information about a specific product, identified by its SKUProduct update: Users should be able to update existing product information, such as name, description, or priceProduct description update: The API should provide an endpoint to update the description onlyProduct deletion: The API should allow users to delete a product from the system, identified by its SKUUnique SKU constraint: The API should enforce a constraint to ensure that each product has a unique SKU, preventing duplicate products with the same identifier

Now that we have identified the requirements, the next step is to identify our resources.

Identifying the resources

A REST API can have one or more resources, and it can also have a hierarchical URI structure. A hierarchical URI structure is a way of organizing resources in a URL hierarchy that reflects the relationships between those resources. In a hierarchical URI structure, resources are arranged in a tree-like format, where each segment of the URL represents a level of the hierarchy.

URI or URL?

In the context of REST APIs, we often use the acronyms URI (which stands for Uniform Resource Identifier) and URL (which stands for Uniform Resource Locator) interchangeably. To be precise, URLs are a subset of URIs. There is a second subset of URIs called URNs (which stands for Uniform Resource Names). The advantage of a URL over a URN is that besides being a unique identifier of the resource, it also contains information that can be used to locate and access the resource: protocol, hostname, and path. The path part of a URL supports a hierarchical structure such as the sequence of folders and a filename that you know from filesystem paths.

Let’s take the following as an example:

https://example.com/blog/posts/12

In this URI, we have the following:

https://example.com is the base URL/blog represents the top-level resource, indicating that we are accessing the blog section of a website/posts is a sub-resource under the /blog resource, representing a collection of blog posts/12 is a specific blog post identified by its unique identifier

In our case, we have only one resource, which is the product, so we have only /products.

Resources should be nouns; they should not be verbs. For example, /products/create should not be used; instead, use the corresponding HTTP method for this action. This is essential for adhering to level 2 of the Richardson Maturity Model.

In English, many verbs can be used as nouns too, for example, /products/quote. When we make a POST request to this resource, it means create a quote. The verb part of the sentence is represented by the correct HTTP method.

Resources map to business entities and the API usually works with multiple entities of the same type. When creating or listing resources (entities) of a particular type, we are working with a collection of objects. For collection resources, we use the plural form of the noun – for example, products instead of product because we want to support operations on the collection of products.

RFC 3986 defines a URI as a compact sequence of characters that identifies an abstract or physical resource. According to RFC 1738, a URL is a specific type of URI that represents the location of a resource accessible via the internet. Thus, a URI can be further classified as a locator, a name, or both, with the term URL referring to the subset of URIs. This means that all URLs are URIs, but not all URIs are URLs. RFC 2141 further defines URNs as another type of URI that names a resource in a persistent, location-independent manner.

Now that we have identified the resources, the next step is to define the resource structure.

Defining the resource structure

After identifying the resources, we should identify the attributes of the resources and any relationships that are important in the API. The attributes represent the data fields associated with the resource. Consider the data types, constraints, and any required or optional attributes for each resource. A relationship indicates how the resources are related to each other and whether they have any hierarchical or nested relationships. For example, a user may have multiple orders associated with them, or a product may belong to a specific category.

In our case, we have only one resource, which is the product, which should have these attributes:

name: The name of the productsku: The unique key of the productdescription: A description of the productprice: The price of the product

We can also define the rules for these attributes in this step:

name: Required field, with a string with a length between 3 and 255 characterssku: Required field, with the pattern AA99999description: Required field, with a string with a length between 10 and 255 charactersprice: Required field, with a value greater than 0

After this step, we can design the endpoints.

Designing the endpoints

To design the endpoints, it is important to know the HTTP methods and the HTTP status codes. Before talking about this, though, we should go one step back and understand how it started.

The HTTP methods and principles we are going to share here follow the guidelines from Microsoft mentioned in the previous chapter. Any REST guidelines should adhere to the internet standard known as RFC 9110, the updated version of RFC 2616. RFC stands for Request for Comments. RFC specifies HTTP, TCP, IP, SMTP, and many other vital internet protocols. Fielding’s dissertation, titled Architectural Styles and the Design of Network-based Software Architectures, was an important source for RFC 2616, defining the HTTP/1.1 protocol.

HTTP methods (verbs)

HTTP defines several methods (also known as verbs) that indicate the action to be performed on a resource. The most used HTTP methods in RESTful APIs are the following:

GET: The GET method requests are used to retrieve resource representations, and they should not alter the server state. They are safe and idempotent, meaning they do not have any side effects on the server and can be repeated without changing the server state. (Think about the get method of a Map in Java.)POST: The POST method requests are used to create new resources or generally submit data to be processed by the server. They are non-idempotent, meaning that each request is unique and may have side effects on the server. (Think about the ++ operator in Java; the result will be different if it is evaluated multiple times.)PUT: These requests are typically used to create or update the entire representation of a resource. They are idempotent, meaning that sending the same request multiple times should have the same effect as sending it once. (Think about the put method of a Map in Java.)PATCH: This is like PUT but used to apply partial modifications to a resource. It is often used when you want to update only certain fields of a resource. (Think about a setter method of a Java Bean/POJO.)DELETE: This method is used to remove a resource from the server. The method is idempotent, meaning that sending the same request multiple times should result in the same state on the server.

HTTP status codes

HTTP status codes are three-digit numbers that a server sends back to the client after receiving a request. They indicate the outcome of the request and provide information about the status of the server or the requested resource. All HTTP status codes are grouped into the following categories:

1xx Informational: This indicates that the request was received and is being processed.2xx Success: This indicates that the request was received, understood, and processed successfully by the server.3xx Redirection: This indicates that further action is needed to complete the request. The client may need to redirect to a different URI.4xx Client Error: This indicates that there was an error in the client’s request.5xx Server Error: This indicates that there was an error on the server side while processing the request.

Now that we understand HTTP methods and statuses, we can define the API endpoints.

Defining the endpoints for our API

Let’s define the endpoints for the resource we identified in the previous step. We will use the HTTP methods with the products resources to ensure we can perform all the necessary operations as outlined in the requirements phase.

GET /products

This endpoint will be responsible for returning a list of products. We should return a 200 (ok) HTTP status with the products.

PUT /products/{id}

This endpoint will be responsible for creating or updating the product. PUT is an idempotent method, so we can call it many times and the result will be the same. In case of success, we should return 201 (created) if the product doesn’t exist and 200 if the product already exists.

We could also return 202 (accepted) if the product will be processed in the future as an asynchronous task, which is not the case here.

If we decided to use the POST method, we would need to choose between throwing an exception if the product already exists – this exception could be 409 (conflict) – or creating another product. In our case, because the SKU is not generated by the application, it is an attribute passed to the API, and we cannot have two products with the same SKU, so we will need to return 409 and have another endpoint that would be responsible for updating the resource as it is a requirement. Instead of doing this, we can use the PUT method, which can create or update the resource.

According to RFC 9110, Section 9.3.4, “The fundamental difference between the POST and PUT methods is highlighted by the different intent for the enclosed representation. The target resource in a POST request is intended to handle the enclosed representation according to the resource’s own semantics, whereas the enclosed representation in a PUT request is defined as replacing the state of the target resource. Hence, the intent of PUT is idempotent and visible to intermediaries, even though the exact effect is only known by the origin server”.

Proper interpretation of a PUT request presumes that the user agent knows which target resource is desired. To get a better insight, please refer to https://www.rfceditor.org/rfc/rfc9110.html#section-9.3.4.

DELETE /products/{id}

This endpoint should remove the product. We can return 204 (no content) in case the product is removed. Even if the product does not exist, we can return 204, as the method is idempotent, meaning that sending the same request multiple times should result in the same state on the server.

PATCH /products/{id}

This endpoint should be used to update the description of the product. As it is a partial update of a resource, it is recommended to use PATCH. The PATCH method was introduced in RFC 5789 as a partial update that doesn’t need to be idempotent. If the product does not exist, we can return a 404 (Not found) error. In case of success, we can return the updated product data and a 200 HTTP status.

GET /products/{id}

This endpoint is responsible for returning the details of a single product by the ID. If the product does not exist, we can return a 404 (Not found) error.

In case of success, we should return the product representation and a 200 HTTP status.

Now that we have defined our endpoints, let’s see the possible errors that we may encounter and how we can prepare for them effectively.

Error handling

Preparing for common issues by defining possible errors can help us implement a more reliable API. We have already discussed some errors in the previous step; however, let’s get deep into it and see the most common HTTP status codes in the 4xx range.

The most common HTTP status codes in the 4xx range, which indicates client errors, are the following:

400 Bad Request: This status code indicates that the server could not understand the client’s request due to invalid syntax or a malformed request message.401 Unauthorized: This status code indicates that the client needs to authenticate itself to access the requested resource. It typically occurs when the client fails to provide proper authentication credentials or access tokens.403 Forbidden: This status code indicates that the client is authenticated, but it does not have permission to access the requested resource. It may be due to insufficient permissions or access control restrictions imposed by the server.404 Not Found: This status code indicates that the server could not find the requested resource. It is commonly used to indicate that the URI provided by the client does not correspond to any known resource on the server.405 Method Not Allowed