14.3 Endpoint Resource
The endpoint resources allow a service consumer to discover the URLs of available service providers. The list of endpoints can be queried with a GET request on the following URL:
This request will return an SData feed with one entry for each registered endpoint. Each entry will contain an XML payload describing the provider’s URL as an endpoint, typically:
<endpoint xmlns="http://schemas.sage.com/sdata/registry/2009">
<title>Accounts 50 GCRM 1.0 demo</title>
<description>URL for Accounts 50 GCRM 1.0 demo integration</description>
<endpointType>dataSet</endpointType>
<protocol>http</protocol>
<host>wwww.example.com</host>
<port>80</port>
<applicationName>accounts50</applicationName>
<contractName>GCRM</contractName>
<contractVersion>1.0</contractVersion>
<dataSetName>demo</dataSetName>
<url>http://www.example.com/sdata/accounts50/gcrm/demo</url>
<isBrowsable>true</isBrowsable>
<aliveStamp>2009-04-02T08:32:19Z</aliveStamp>
<properties>
<property name="performanceIndex" ns="http://schemas.example.com/loadbalance">87</property>
</properties>
</endpoint>
The following table describes the elements of this XML payload:
| Element | Example Value | Description |
|---|---|---|
| title | Accounts 50 GCRM 1.0 demo | User friendly title for the endpoint |
| description | URL for Accounts 50 ... | Description of the endpoint |
| endpointType | dataSet |
One of the following endpoint types:
|
| protocol | http | The protocol: http or https |
| host | www.example.com | The host |
| port | 80 | The TCP/IP port |
| applicationName | accounts50 | The application name |
| contractName | GCRM | The contract name |
| contractVersion | 1.0 | The version of the contract |
| dataSetName | demo | The name of the dataSet |
| url | http://www.example.com/sdata/accounts50/gcrm/demo | The endpoint URL which has been registered |
| isBrowsable | true | Indicates whether the service supports GET operations on the URL |
| aliveStamp | 2009-04-02T08:32:19Z | Most recent timestamp at which the endpoint was known to be alive. |
| properties | list of <property> elements with name value pairs | Custom endpoint properties |
The endpointType indicates what the URL represents: an application, a contract or a dataSet. The following table gives examples of the three endpoint types
| endpointType | URL | Description |
|---|---|---|
| application | http://www.example.com/sdata/accounts50 | The URL represents an application. If isBrowsable is true, a GET request on the URL should enumerate the contracts (see Intermediate URLs). |
| contract | http://www.example.com/sdata/accounts50/gcrm | The URL represents a contract in the context of an application. If isBrowsable is true, a GET request on the URL should enumerate the data sets (see Intermediate URLs). |
| dataSet | http://www.example.com/sdata/accounts50/gcrm/demo | The URL gives access to a specific dataset for a given application and contract. isBrowsable SHOULD be true on dataSet URLs. A GET request on the URL should enumerate the resource kinds (see Intermediate URLs). |
The isBrowsable element indicates if the service supports GET operations on the URL. Services should always support GET operations on dataSet URLs, returning a feed that enumerates the resource kinds. On the other hand, services may or may not support GET operations on application and contract URLs, depending on how the application is deployed. For example, it an application is deployed with one virtual directory per contract, then it contract endpoints should be browsable but its application endpoint will not be browsable (because it is not mapped to a virtual directory).
The properties element provides a simple mechanism to associate arbitrary property values with endpoints. This feature allows applications to take advantage of the registry infrastructure to store custom information alongside registry entries. This feature is designed to handle simple property lists, not complex data structures. SData does not prescribe any list of property names. Service implementers are free to choose their property names and they are encouraged to scope them with a namespace via the ns attribute, to guard against potential name collisions. In the example above, this feature is used to store a performanceIndex value which may be used to balance the load between several service endpoints.
The registry service MUST support basic queries on its endpoints URL (see query conformance levels in Query Language section). So, for example, a consumer should be able to request the list of all GCRM contracts exposed via HTTPS with a GET on the following URL:
http://www.example.com/sdata/$system/registry/-/endpoints?where=contractName eq 'GCRM' and protocol eq 'https'