Api 101

Modern web applications commonly expose APIs that allow clients to interact with them. A well-crafted web API should prioritize:

1. Platform Independence: The API should be accessible to any client, irrespective of its internal implementation. This necessitates the use of standard protocols and the establishment of a mutual understanding between the client and the web service regarding data exchange formats.

2. Service Evolution: The web API should be capable of evolving and incorporating new features independently of client applications. As the API progresses, existing client applications should seamlessly function without requiring modifications. All functionalities must be discoverable, enabling client applications to make full use of them.

This guidance addresses key considerations for designing an effective web API.

What is REST?

In 2000, Roy Fielding introduced Representational State Transfer (REST) as an architectural approach to web service design. REST is an architectural style for constructing distributed systems based on hypermedia. While REST is not tied to any specific underlying protocol, it is commonly associated with HTTP in most implementations. This guide primarily focuses on designing REST APIs for HTTP.

A significant advantage of REST over HTTP is its adherence to open standards, avoiding specific implementations for the API or client applications. For instance, a RESTful web service could be developed in ASP.NET, and client applications can utilize any language or toolset capable of generating HTTP requests and parsing HTTP responses.

Here are key design principles for creating RESTful APIs using HTTP:

• Resource-Centric Design: REST APIs revolve around resources, which can be any object, data, or service accessible to the client.

• Resource Identification: Each resource has a unique identifier in the form of a URI. For instance, the URI for a specific customer order might be: [example URI].