1. Introduction

1. Introduction

Applications other than Web browsing often use HTTP [HTTP] as a substrate, a practice sometimes referred to as creating "HTTP-based APIs", "REST APIs", or just "HTTP APIs". This is done for a variety of reasons, including:

• familiarity by implementers, specifiers, administrators, developers, and users;

• availability of a variety of client, server, and proxy implementations;

• ease of use;

• availability of Web browsers;

• reuse of existing mechanisms like authentication and encryption;

• presence of HTTP servers and clients in target deployments; and

• its ability to traverse firewalls.

These protocols are often ad hoc, intended for only deployment by one or a few servers and consumption by a limited set of clients. As a result, a body of practices and tools has arisen around defining HTTP-based APIs that favour these conditions.

However, when such an application has multiple, separate implementations, is deployed on multiple uncoordinated servers, and is consumed by diverse clients (as is often the case for HTTP APIs defined by standards efforts), tools and practices intended for limited deployment can become unsuitable.

This mismatch is largely because the API's clients and servers will implement and evolve at different paces, leading to a need for deployments with different features and versions to coexist. As a result, the designers of HTTP-based APIs intended for such deployments need to more carefully consider how extensibility of the service will be handled and how different deployment requirements will be accommodated.

More generally, an application protocol using HTTP faces a number of design decisions, including:

• Should it define a new URI scheme? Use new ports?

• Should it use standard HTTP methods and status codes or define new ones?

• How can the maximum value be extracted from the use of HTTP?

• How does it coexist with other uses of HTTP -- especially Web browsing?

• How can interoperability problems and "protocol dead ends" be avoided?

Section 2 defines when this document applies, Section 3 surveys the properties of HTTP that are important to preserve, and Section 4 contains best practices for the specification of applications that use HTTP.

It is written primarily to guide IETF efforts to define application protocols using HTTP for deployment on the Internet but might be applicable in other situations. Note that the requirements herein do not necessarily apply to the development of generic HTTP extensions.

This document obsoletes [RFC3205] to reflect the experience and developments regarding HTTP in the intervening time.