Previous Page Arrow Next Page Arrow

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:

http://www.example.com/sdata/$system/registry/-/endpoints

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:
  • application
  • contract
  • dataSet
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'

Previous Page Arrow Next Page Arrow