2.2.3 URI Format: Resource Addressing Rules

  • Article

The Atom Publishing (AtomPub) Protocol specifies operations for publishing and editing resources by using HTTP, but does not constrain the form of the URIs, as specified in [RFC3986], that are used to identify the resources (see [RFC5023] section 4.1). This document extends AtomPub by defining a mapping from elements in an Entity Data Model (EDM), described by using a conceptual schema definition language (CSDL) document, to the resource types defined in [RFC5023] section 4.2. See Abstract Data Model (section 2.2.1) for a mapping of EDM constructs to AtomPub resources.

As specified in [RFC5023] (section 4.1), the Atom Publishing Protocol [RFC5023] specifies the formats of the representations that are exchanged and the actions that can be performed on the Internationalized Resource Identifiers (IRIs) embedded in those representations. AtomPub does not constrain the form of the URIs that are used. Following that paradigm, this section and its subsections defines a set of recommended, but not required, rules for constructing a URI or IRI to identify the various parts of the data and metadata in an EDM.

Servers and clients MAY use alternate URI path construction rules because HTTP [RFC2616] specifies that the URI space of each server is controlled by that server. The OData protocol imposes no further constraints on that control when constructing the authority and path segments of a URI. However, servers that conform to this specification MUST honor the rules for query string construction as defined in this section and its subsections.

Server authors are encouraged to follow the URI path construction rules, in addition to the required query string rules, that are defined in this specification when possible. Such consistency promotes an ecosystem of reusable client components and libraries.

Before an IRI can be used by an HTTP request, the IRI is first converted to a URI, according to the algorithm defined in [RFC3987] section 3.1. For the remainder of this document, the term URI is used to refer to a URI or an IRI that has been converted to a URI.