Why should one go through the tedium of designing a REST web API

As I prepare for my upcoming REST API presentation, I’m cataloging these slides and concepts in my personal knowledge base (KB). Leveraging the power of HTML as an exceptional presentation system, I can craft captivating and interactive content. With the inclusion of these “slides,” you’re welcome to conveniently reuse the material, with proper attribution under CC (Creative Commons) guidelines.

Slide 1: Introduction

As Humans, we easily reason about “things”, in the sense of physical objects.
Imagine you have jars on a shelf
- we add things
- we modify things
- we get things
- we remove things

Slide 2: What is REST API?

Definition: REST (Representational State Transfer) API is an architectural style for designing networked applications, particularly web services, that leverages the existing protocols and conventions of the World Wide Web.
Key Components:
- Resources (A.k.a the stuff): Entities that can be accessed and manipulated via the API.
- URIs (Uniform Resource Identifiers) (where are they on the shelf): Unique addresses that identify resources.
- HTTP Verbs (GET, POST, PUT, DELETE) (what do we do with it): Actions performed on resources.
- Representation (How do we elaborate information): Data formats (e.g., JSON, XML) used to represent resources.

Slide 3: Why REST API?

Simplicity: REST API follows a straightforward and intuitive design philosophy.
Scalability: RESTful architecture allows for easy scaling and handling of large volumes of requests.
Stateless: Each request sent to a REST API is independent and self-contained, ensuring scalability and reliability.
Interoperability: REST APIs can be consumed by a wide range of clients, including web browsers, mobile applications, and IoT devices.
Flexibility: REST API can support multiple data formats, making it versatile for various applications.

Slide 4: Constraints of RESTful APIs

Stateless Communication: Each request from the client contains all the necessary information for the server to understand and process it. Server does not maintain session state.
Client-Server Architecture: Clear separation between the client (user interface) and the server (data storage and processing).
Cacheability: Responses can be cached to improve performance and reduce server load.
Layered System: RESTful APIs can be designed in a layered architecture, where multiple layers (e.g., load balancers, proxies) can process the request.
Uniform Interface: Consistent usage of HTTP verbs (GET, POST, PUT, DELETE) and standard data formats (JSON, XML) for accessing and manipulating resources.

Slide 6: Best Practices for REST API Design

Resource Naming: Use clear and meaningful nouns (and not verbs) for resources in the URIs.
Versioning: Consider versioning your API to ensure backward compatibility.
Pagination: Implement pagination to manage large result sets efficiently.
Error Handling: Provide detailed error messages to assist developers in troubleshooting issues.
Documentation: Create comprehensive and easy-to-understand API documentation to guide developers.

Slide 7: An example close to home

Let’s say you have a jar endpoint http://my-domain.com/v1/api/jar/

A GET to http://my-domain.com/v1/api/jar/big-jar would look like

        
      
{
"id": "big-jar",
"description": "on the kitchen counter, by the sink",
"label": "dried apricots",
"content": "http://my-domain.com/v1/api/jar/big-jar/content",
}

If I was to change label, I could PATCH http://my-domain.com/v1/api/jar/big-jar
1 2 3 { "label": "Dried Apricots 2023-07-17" }
If I wanted to add an apricot, I would POST http://my-domain.com/v1/api/jar/big-jar/content
1 2 3 4 5 { "id": 3247892397, "weight": "60g", "radius": "5cm" }
Slide 8: Why should I document, if REST is so easy?
Verbs and well-defined business resources can go a long way in describing what can be done with an API.
How would you express that some entities are linked in a web environment?
HATE(OAS) the rest….

Slide 9: HATEOAS for the rest of us: putting links, rather than giving documentation

It really is a constraint of REST, but is seldom implemented.
Basically, put links in the response objects.

        
      
{
    "account": {
        "account_number": 12345,
        "balance": {
            "currency": "usd",
            "value": 100.00
        },
        "links": {
            "deposits": "/accounts/12345/deposits",
            "withdrawals": "/accounts/12345/withdrawals",
            "transfers": "/accounts/12345/transfers",
            "close-requests": "/accounts/12345/close-requests"
        }
    }
}

Slide 10: HAL, or “reserved” names

Not really a standard, just a popular idea.
Use _<Something> rather than attributes, so one can distinguish between object attributes and navigational attributes.

        
      
{
  "title": "My slides on rest",
  "date": "today",
  "tags": ["rest", "DIY"],
  "links": {
    "main_topic": "/topics/REST",
    "related": [
      "/articles/how-to-test-with-hateoas"
    ]
  },
  "_links": {
    "self": "/articles/rest-apis-and-you.html",
    "collection": "/articles/",
    "next": null,
    "previous": "/articles/kubernetes-self-hosting.html",
    "tags": "/articles/rest-apis-and-you.html/tags"
  }
}

In this example, one would need _links.tags to operate on tags.

Slide 11: Event-Driven REST API

Concept: REST API can leverage event-driven architectures, where events are used for asynchronous communication between components or services.
Event Brokers: Introduce the concept of event brokers (e.g., message queues, publish-subscribe systems) that enable the distribution and consumption of events.
Benefits of Event-Driven Integration:
- Loose coupling: Components communicate indirectly through events, reducing dependencies and allowing for greater flexibility.
- Scalability: Event-driven architecture supports distributed processing, enabling horizontal scalability.
- Real-time updates: REST API can publish events, allowing clients to receive real-time updates without constant polling.

Slide 12: Benefits of Event-Driven Integration

Scalability: Event-driven architecture enables horizontal scalability by distributing events across multiple consumers.
Real-time updates: REST API can push events to subscribers in real-time, providing up-to-date information to connected clients.
Loose coupling: Event-driven integration allows components to communicate without direct dependencies, enabling flexibility and agility.
Rebuildability: Event-driven REST API promotes the ability to rebuild and evolve the system by decoupling components and allowing them to independently evolve and be replaced, ensuring long-term maintainability and scalability.

Note: The term “rebuildability” refers to the system’s ability to be rebuilt and restructured over time, ensuring that components can be modified, added, or replaced without disrupting the overall functionality of the system. This aspect of event-driven REST API design is essential for ensuring long-term success and adaptability.

Slide 13: It is up to us!

Empower your APIs with purposeful design and intuitive standards.
Speak the language of your business, not just technology.
Craft APIs that are maintainable, adaptable, and a joy to use.
Own your API design. Craft excellence that resonates with business and developers alike.

Slide 14: Conclusion

Recap: REST API is not limited to web-based communication but can also integrate with event brokers, enabling event-driven integration and expanding its capabilities.
Web-Based REST API: Ideal for client-server communication, web applications, and interoperability with other web-based services.
Event-Driven REST API: Enables real-time updates, decoupled communication, and integration with event-driven architectures.
It is up to us to grow our own API environment.
Important essays: https://htmx.org/essays/
Q&A: Open the floor for any additional questions or discussions.