2.1 Resource Collection URL
Let’s start with a typical SData URL for a resource collection:
http://www.example.com/sdata/myApp/myContract/prod/accounts?startIndex=21&count=10
This URL has the following components:
| Example | Component Name | Description / Comments |
|---|---|---|
| http | Protocol | https is also allowed. |
| www.example.com | Server name | IP address is also allowed (192.168.1.1). Can be followed by port number. For example www.example.com:5493) 5493 is the recommended port number for SData services that are not exposed on the Internet. |
| sdata | Virtual Directory | Should be sdata, unless the technical framework imposes something different. |
| myApp | Application | Name of the application. |
| myContract | Contract name | An SData service can support several “integration contracts” side-by-side. For example, a typical Sage ERP service will support a crmErp contract which exposes the resources required by CRM integration (with schemas imposed by the CRM/ERP contract) and a native or default contract which exposes all the resources of the ERP in their native format. |
| prod | Dataset | Identifies the dataset when the application gives access to several datasets, such as several companies and production/test datasets. If the application can only handle a single dataset, or if it can be configured with a default dataset, a hyphen can be used as a placeholder for the default dataset. For example, if prod is the default dataset in the example above, the URL could be shortened as: http://www.example.com/sdata/myApp/myContract/-/accounts?startIndex=21&count=10 If several parameters are required to specify the dataset (for example database name and company id), they should be formatted as a single segment in the URL. For example, myApp/myContract/demodb;acme/accounts -- the semicolon separator is application specific, not imposed by SData. |
| accounts | Resource Kind | This URL segment identifies the kind of resource that is queried (account, contact, salesOrder, etc.) This URL returns the collection of all account resources, as an Atom feed. If the contract exposes a large number of resources kinds, a functional group can be inserted before the resource kind segment (eventually a hierarchy of functional groups), which act as a folder (a hierarchy of folders) to organize the resources. Typical functional groups would be financials, commercials, HR, etc. |
| startIndex=21 count=10 | Query parameters | The startIndex and count parameters allow the service consumer to request a specific page in a collection. See paging section and query parameters section for details. |
SData URLs MUST comply with this structure. The components listed in the table above MUST be present, unless the URL is an intermediate URL (see Intermediate URLs section) and they MUST be in the right order. There is nevertheless a tolerance on the /sdata virtual directory component. Applications MAY use a different virtual directory name or MAY have more than one segment before the application name if their deployment infrastructure requires it. Such applications SHOULD NOT expose a $system URL (see System and Registry URL section) as the $system component MUST be in the /sdata virtual directory.