2.2.7.2.8 RetrieveServiceDocument Request

The purpose of the RetrieveServiceDocument request is to enable a client to retrieve the Service Document describing the collection of resources exposed by a data service, as described in Service Document (section 2.2.3.7.1).

AtomPub, as specified in [RFC5023], describes the retrieval of an AtomPub Service Document in an HTTP response payload. This document extends that behavior to allow additional representations of the Service Document to be retrieved by a data service client. A client states the desired response payload format by using the Accept (section 2.2.5.1) request header. This document defines three such representations of Service Documents: Service Document (section 2.2.6.2.7) for AtomPub, Service Document ([MS-ODATAJSON] section 2.1.16) for JSON, and Service Document (section 2.2.6.3.12) for Verbose JSON.

A RetrieveServiceDocument Request MUST use the HTTP GET method and the URI specified by the client in the HTTP request line MUST be a valid data service URI that identifies the service root (section 2.2.3.2).

If the RetrieveServiceDocument request was successful, the response MUST have a 200 status code, as specified in [RFC2616], and the response body MUST be formatted as specified in Service Document (section 2.2.6.2.7) for AtomPub-based requests, Service Document ([MS-ODATAJSON] section 2.1.16) for JSON-based requests, and Service Document (section 2.2.6.3.12) for Verbose JSON-based requests. If the RetrieveServiceDocument request is not successful (for example, an error occurred while processing the request), the response MUST be formatted according to Error Response (section 2.2.8.1).

The syntax of a RetrieveServiceDocument request is defined as follows:

 retrieveServiceDocument-Req = retrieveServiceDocument-ReqLine
                               retrieveServiceDocument-ReqHeaders
  
 retrieveServiceDocument-ReqLine = "GET"
                                   SP serviceRoot
                                   retrieveServiceDocument-QueryOps
                                   SP HTTP-Version
                                   CRLF
  
 retrieveServiceDocument-ReqHeaders = [DataServiceVersion]    ; see section 2.2.5.3
                                      [MaxDataServiceVersion] ; see section 2.2.5.7
                                      [Accept]                ; see section 2.2.5.1
                                      *(HTTP-Header-Types)
  
 serviceRoot                        = ; see section 2.2.3.2
  
 retrieveServiceDocument-QueryOps   = ["?" customQueryOption
                                       *("&" customQueryOption)]
                                      ; see section 2.2.3.6

The syntax of a response to a successful RetrieveServiceDocument request is defined as follows:

 retrieveServiceDocument-Resp = Status-Line        ; see [RFC2616] section 6.1.1
                                retrieveServiceDocument-RespHeaders
                                CRLF
                                retrieveServiceDocument-RespBody
  
 retrieveServiceDocument-RespHeaders = DataServiceVersion ; see section 2.2.5.3
                                       [Content-Type]     ; see section 2.2.5.2
                                       *(HTTP-Header-Types)
  
 retrieveServiceDocument-RespBody   = <Service Document formatted by using AtomPub
                                        as per section 2.2.6.2.7>
                                      /<Service Document formatted by using JSON as per
                                       [MS-ODATAJSON] (section 2.1.16)>
                                      /(begin-object
                                        quotation-mark "d" quotation-mark
                                        name-seperator
                                        VJsonServiceDocument
                                        end-object)
                                        ; see section 2.2.6.3.11