URI Conventions (OData Version 2.0)

URI Conventions (OData Version 2.0)

OData Version 4.0 is the current recommended version of OData. OData V4 has been standardized by OASIS and has many features not included in OData Version 2.0.

 Go to OData Version 4.0

Introduction

The Open Data Protocol (OData) enables the creation of REST-based data services, which allow resources, identified using Uniform Resource Identifiers (URIs) and defined in a data model, to be published and edited by Web clients using simple HTTP messages. This specification defines a set of recommended (but not required) rules for constructing URIs to identify the data and metadata exposed by an OData server as well as a set of reserved URI query string operators, which if accepted by an OData server, MUST be implemented as required by this document.

The [OData:Atom] and [OData:JSON] documents specify the format of the resource representations that are exchanged using OData and the [OData:Operations] document describes the actions that can be performed on the URIs (optionally constructed following the conventions defined in this document) embedded in those representations.

It is encouraged that servers follow the URI construction conventions defined in this specification when possible as such consistency promotes an ecosystem of reusable client components and libraries.

The terms used in this document are defined in the [OData:Terms] document.

1. URI Components

A URI used by an OData service has up to three significant parts: the service root URI, resource path and query string options. Additional URI constructs (such as a fragment) MAY be present in a URI used by an OData service; however, this specification applies no further meaning to such additional constructs.

Structure of an OData URI, which consists of a scheme, host, optional colon and port, service root, optional resource path, and optional question mark followed by query options.

The following are two example URIs broken down into their component parts:

Two example URIs with their component parts labeled. The first URI is "https://services.odata.org/OData/OData.svc", which is the service root URL. The second URI starts with the same service root URL, but also has the two following additional parts. The resource path part is "/Category(1)/Products", and the query options part is "?$top=2&$orderby-name".

2. Service Root URI

The service root URI identifies the root of an OData service. The resource identified by this URI MUST be an AtomPub Service Document (as specified in [RFC5023]) and follow the OData conventions for AtomPub Service Documents (or an alternate representation of an Atom Service Document if a different format is requested). OData: JSON Format specifies such an alternate JSON-based representation of a service document. The service document is required to be returned from the root of an OData service to provide clients with a simple mechanism to enumerate all of the collections of resources available for the data service.

Example Request URI	OData Service URI
https://services.odata.org:8080	https://services.odata.org:8080
https://services.odata.org/OData/OData.svc/Categories	https://services.odata.org/OData/OData.svc/

3. Resource Path

The resource path construction rules defined in this section are optional. OData servers are encouraged to follow the URI path construction rules (in addition to the required query string rules) as such consistency promotes a rich ecosystem of reusable client components and libraries.

The resource path section of a URI identifies the resource to be interacted with (such as Customers, a single Customer, Orders related to Customers in London, and so forth). The resource path enables any aspect of the data model (Collections of Entries, a single Entry, Properties, Links, Service Operations, and so on) exposed by an OData service to be addressed.

3.1. Addressing Entries

---

The basic rules for addressing a Collection (of Entries), a single Entry within a Collection, as well as a property of an Entry are illustrated in the figure below.

Structure of a resource path, showing multiple structure options as follows. To address an entry, one must first address a specific collection. A Collection may optionally be followed by a forward slash and $count. Alternatively, it may be followed by a KeyPredicate. After this KeyPredicate is one or more forward slash and navigation property, one or more forward slash and ComplexType, optional one or more forward slash and Property, and optional one or more forward slash and $value. The navigation property may be either a NavPropSingle or a NavPropCollection. If the collection is chosen, it is directly followed by either a KeyPredicate or an optional forward slash and $count. If the latter option is chosen, this must be the last navigation property in the sequence.

• Collection: The name of a Collection or Service Operation (which returns a Collection of Entries) exposed by the service.
• KeyPredicate: A predicate that identifies the value(s) of the key Properties of an Entry. If the Entry has a single key Property the predicate may include only the value of the key Property. If the key is made up of two or more Properties, then its value must be stated using name/value pairs. More precisely, the syntax for a KeyPredicate is shown by the following figure.

Structure of a KeyPredicate, which starts and ends with an opening and closing parenthesis, respectively. Between the parentheses may be either a single KeyValue or a three-piece portion containing a Property, equals sign, and KeyValue. There may be more than one three-piece portion if these portions are separated by commas.

• NavPropSingle: The name of a Navigation Property defined by the Entry associated with the prior path segment. The Navigation Property must identify a single entity (that is, have a "to 1" relationship).
• NavPropCollection: Same as NavPropSingle except it must identify a Collection of Entries (that is, have a "to many" relationship).
• ComplexType: The name of a declared or dynamic Property of the Entry or Complex Type associated with the prior path segment.
• Property: The name of a declared or dynamic Property of the Entry or Complex Type associated with the prior path segment.

For OData services conformant with the addressing conventions in this section, the canonical form of an absolute URI identifying a single Entry is formed by adding a single path segment to the service root URI. The path segment is made up of the name of the Collection associated with the Entry followed by the key predicate identifying the Entry within the Collection. For example the URIs https://services.odata.org/OData/OData.svc/Categories(1)/Products(1) and https://services.odata.org/OData/OData.svc/Products(1) represent the same Entry, but the canonical URI for the Entry is https://services.odata.org/OData/OData.svc/Products(1).

Examples

The example URIs below follow the addressing rules stated above and are based on the reference service and its service metadata document available at https://services.odata.org/OData/OData.svc/ and https://services.odata.org/OData/OData.svc/$metadata.

https://services.odata.org/OData/OData.svc/Categories

• Identifies all Categories Collection.
• Is described by the Entity Set named "Categories" in the service metadata document.

https://services.odata.org/OData/OData.svc/Categories(1)

• Identifies a single Category Entry with key value 1.
• Is described by the Entity Type named "Categories" in the service metadata document.

https://services.odata.org/OData/OData.svc/Categories(1)/Name

• Identifies the Name property of the Categories Entry with key value 1.
• Is described by the Property named "Name" on the "Cate