MSDN Documentation

RESTful API Fundamentals

Welcome to this tutorial on RESTful API Fundamentals. This guide will introduce you to the core concepts and principles behind Representational State Transfer (REST) and how it's used to build robust and scalable web services.

What is REST?

REST (Representational State Transfer) is an architectural style, not a protocol. It defines a set of constraints that, when followed, result in a loosely coupled, scalable, and highly performant web service. RESTful APIs leverage standard HTTP methods to perform operations on resources.

Key Principles of REST

• Client-Server Architecture: Separation of concerns between the client (user interface) and the server (data storage and logic).
• Statelessness: Each request from the client to the server must contain all the information needed to understand and process the request. The server should not store any client context between requests.
• Cacheability: Responses must implicitly or explicitly define themselves as cacheable or non-cacheable to improve client performance.
• Uniform Interface: This is a core principle that simplifies and decouples the architecture. It includes:
  • Identification of resources.
  • Manipulation of resources through representations.
  • Self-descriptive messages.
  • Hypermedia as the Engine of Application State (HATEOAS).
• Layered System: The client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way.
• Code on Demand (Optional): Servers can extend client functionality by transferring executable code.

HTTP Methods and REST

RESTful APIs typically use the standard HTTP methods (verbs) to indicate the desired action to be performed on a resource.

• GET: Retrieves a representation of a resource. Should be safe and idempotent.
• POST: Submits data to be processed to a specified resource, often causing a change in state or side effects on the server.
• PUT: Updates a resource at a specified URI. If the resource does not exist, it may be created. Idempotent.
• DELETE: Deletes a specified resource. Idempotent.
• PATCH: Applies partial modifications to a resource.

RESTful URIs

Resources are identified by URIs (Uniform Resource Identifiers). A common pattern is to use nouns to represent resources.

Example:

https://api.example.com/users
https://api.example.com/products/123

Representations

Resources are manipulated through their representations. Common formats include JSON and XML. JSON is widely preferred for its simplicity and performance.

JSON Example

{
  "id": 1,
  "name": "Alice Wonderland",
  "email": "alice@example.com",
  "isActive": true
}

Status Codes

HTTP status codes are crucial for communicating the outcome of an API request. Here are some common ones:

• 2xx Success:
  • 200 OK: Standard response for successful HTTP requests.
  • 201 Created: The request has succeeded and has created a new resource.
  • 204 No Content: The server successfully processed the request and is not returning any content.
• 4xx Client Errors:
  • 400 Bad Request: The server cannot or will not process the request due to something that is perceived to be a client error.
  • 401 Unauthorized: Authentication is required and has failed or has not yet been provided.
  • 404 Not Found: The requested resource could not be found on the server.
  • 405 Method Not Allowed: The request method is known by the server but is not supported by the target resource.
• 5xx Server Errors:
  • 500 Internal Server Error: A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
  • 503 Service Unavailable: The server is currently unavailable to handle the request.

Next Steps

In the next tutorial, we will explore how to design effective RESTful APIs and cover topics like versioning, authentication, and error handling in more detail.