EMS 1.0 REST API Design
REST API main topics: Architecture, Design, Data Model, Standard URIs
Contents
Status
This document is a Draft Specification.
Introduction
The following sections discuss the general design principles used in this specification.
Implementation-Dependent Features
Before discussing the design further, it is appropriate to define the scope of this specification by listing those general features of a service that are not specified here.
Authentication
This specification does not define an authentification mechanism. Service providers SHOULD support some authentication mechansim but are free to support a variety of authentication mechanisms. However, in order to ensure interoperability with a broad set of other applications, some standard mechanism such as OAuth SHOULD be supported.
Authorization and Access Control
This specification does not define an authorization mechanism. Service providers SHOULD support some authorization mechanism to control access to resources and the operations that service consumers may perform on them.
Work Flow and Policy Enforcement
This specification does not define a work flow or policy enforcement mechanism. Service providers SHOULD support some mechanism to enforce work flow and policy.
Revision History and Auditing
This specification does not define a revision history or auditing mechanism. Service providers SHOULD provide support for recording the revision history of all resources including their states, the timestamp of the change, and the identity of the entity making the change.
Events and Notification
This specification does not define an event or notification mechanism. Service providers SHOULD support Atom format as a resource representation to enable change monitoring by feed readers.
The Role of RDF
This specification describes the EMS 1.0 resource data model using RDF. Briefly, the RDF data model describes information as statements of the form (subject, predicate, object) which are often referred to as triples. The predicate of a statement either describes a relation between the subject and object resources or an attribute of the subject resource whose value is the object.
The choice of RDF for this purpose, instead of other equally valid approaches such as UML or Entity-Relationship, is motivated by the goal of aligning the data model with Web architectural principles. This use of RDF in no way implies any restriction on how EM services or clients are implemented. We expect tool developers to be able to add support for the EMS 1.0 REST API to existing tools without any need to rewrite those tools using RDF-based techologies.
This specification also defines RDF/XML representations for resources. In general, there are many equivalent ways to serialize a set of RDF triples as RDF/XML. This specification prescribes the way to serialize resources as RDF/XML so that these representations are well-formed XML and may be processed with any of the many available XML processing technologies (e.g. DOM, SAX, !StAX, XSLT, XQuery, etc.). There is no requirement to use a general RDF/XML parser.
The RDF/XML representation is used in examples. However, EM services should support other important formats such as JSON and HTML, as may support other RDF formats, e.g. N3 and Turtle.
An EM client SHOULD use standard HTTP content negotiation to indicate a preference for specific formats.
Resource Types
An EM service manages access to resources that support the estimation and measurement uses cases. The EM service manages the creation, retrieval, update, and deletion of these resources, and maintains their mutual data integrity constraints in the process of doing so.
The EMS 1.0 data model defines several resource types. The data model for each resource type and the data integrity constraints that hold among resources are defined in detail later in this specification. Each EMS 1.0 resource type is identified by a URI that begins with the following URI:
http://open-services.net/ns/ems#
Througout this specification, we use the prefix ems: to abbreviate this URI. For example, ems:Service is an abbreviation for the following URI:
http://open-services.net/ns/ems#Service
EMS 1.0 defines three kinds of resource type, namely domain entities, domain entity lists, and the service root. The domain entity resource types are ems:Project, ems:Scenario, ems:Estimate, ems:Baseline, and ems:Measurement. For each domain entity type, there is an associated list type, i.e. ems:ProjectList, ems:ScenarioList, ems:EstimateList, ems:BaselineList, and ems:MeasurementList. Finally, the ems:Service resource type represents the EM service as a whole.
An EM service contains information about a set of resources of the above types. We will use RDF to describe this information. In RDF terms, the information forms a graph. Each resource is a node in this graph and each triple is an arc in it.
The EM service graph may contain zero or more instances of each domain entity resource type. EM clients may create and delete instances using the REST API. The graph also contains exactly one instance of each associate entity list type and exactly one instance of the service root type. The list and service resources are built-in to the EM service. EM clients may not create or delete the list or service root resources.
Resource Properties
Each resource type has a set of properties which will be described in detail later in this specification. Some of these properties are automatically maintained by the EM service and may not be modified by EM clients. We refer to these as read-only properties. Some read-only properties such as creation date, creator, etc. are system properties that apply to all resources. Other read-only properties, such as list membership, are specific to a given resource type. For example, when a new domain entity resource is created, a membership property that references it is added to its associated list resource.
We refer to properties that may be directly set or modified by EM clients as read-write properties.
HTTP Methods
The REST API supports the usual HTTP methods: GET, PUT, POST, DELETE. In addition, query parameters MAY be appended to resource URLs in order to modify the response of a GET request. The syntax of these query parameters is specified in OSLC Simple Query Syntax V1.
An EM client may retrieve a representation any resource using GET and may modify its read-write properties using PUT. A representation of information about any resource, possibly including information about related resources, may be retrieved using GET with query parameters that specify the properties to include.
An EM client may create a new domain entity resource by POSTing a representation of it to its associated list resource. Any domain entity resource may be deleted using DELETE.
A domain entity list resource contains membership links to each of its associated domain entity resources. An EM client may retrieve a representation that contains a subset of these membership links, and specified properties of the referenced domain entity resources via GET with query parameters. We refer to this as “GET sublist” in the table below.
The following table summarizes the HTTP methods used in the REST API:
| Resource Type |
GET |
GET sublist |
PUT |
POST |
DELETE |
| service root |
yes |
no |
yes |
no |
no |
| domain entity list |
yes |
yes |
yes |
yes |
no |
| domain entity |
yes |
no |
yes |
no |
yes |
This specification defines RDF/XML representations for all resource types. An EM service MUST support RDF/XML representations. An EM service MAY support other representation formats such as JSON, XHTML, Atom, etc. An EM client SHOULD indicate a preference for specific formats using standard HTTP content negotiation.
If a client does not indicate a preference, then a service MUST respond with an RDF/XML representation. If a client indicates a preference, then the service SHOULD attempt to respond with the closest match. If no match is available then the service MUST return an RDF/XML representation.
Distributed Computing
Any domain entity resource is either an ems:Project resource or is related to a unique ems:Project resource. For example, each ems:Scenario resource has exactly one ems:project property that links it to a unique ems:Project resource, and each ems:Estimate resource has exactly one ems:scenario property that links it to a unique ems:Scenario resource, therefore each ems:Estimate resource is related to a unique ems:Project resource. Similarly, ems:Baseline and ems:Measurement resources are related to unique ems:Project resources.
This specification defines behavior in the simple case where all domain entity resources that are related to a given ems:Project resource are managed by the same service. This is a simplifying assumption and affects how resources are discovered and baselined. For example, to find all the estimates for a given project, a query is run on the ems:EstimateList resource that is linked to the same ems:Service resource that is linked to the ems:ProjectList resource that contains the ems:Project resource. Also, when an ems:Baseline resource is created, the service automatically updates the ems:currentBaseline property of the related ems:Project resource.
While it is certainly possible to define a fully distributed REST API for coordinating queries and updates across a group of collaborating EMS service providers, doing so for a 1.0 specification would add a premature level of complexity and cost for implementers.
As more products add support for the EMS 1.0 REST API, it is anticipated that there may be more than EMS 1.0 service provider in a given deployment. An EMS 1.0 service consumer may interact with multiple EMS 1.0 service providers. This causes no difficulty as long as all the resources related to a project are created in the same service provider instance.
In order to build in an evolution path towards a fully distributed REST API, this specification will adopt that policy of specifying that resources related to a given project or intermediate resource SHOULD be created in the same service. If the project or intermediate resource is in a different service then the behavior is undefined. If there is sufficient demand for a fully distributed REST API, then a future EMS specification will define this behavior.
Previous topic: Architecture
Next topic: Data Model
Enter your comments here:
In the HTTP methods section, we say that the list resources take a PUT. If I’m reading the structure of the lists correctly, the only attributes that can be changed by the PUT are dc:Title and dc:Description. Is that right? Those actually will likely never be read by an automated tool (a person may be interested)…an automated tool will get the URL of the list from either the service root, or from a backpointed in one of the resources on the list, then use the URL of the list either to POST a new resource or GET the results of a query. It’s fine, but maybe irrelevant, then, that the list URL accepts PUT, right? It is “protection” for upgrades, I assume, if in a future incarnation of the interface the list has more interesting properties.
– Main/AndyBerner - 05 Apr 2010
Andy, yes, the PUT to a list just lets you modify the title and description so you can customize those properties for the local installation. These properties should be displayed if the client requests an HTML page.
– Main/ArthurRyman - 05 Apr 2010
Category:Rest API main topics
