REST API main topics: Architecture, Design, Data Model, Standard URIs
Contents
Status
This document is a Draft Specification.
Introduction
The Estimation and Measurement Service Version 1.0 (EMS 1.0) specification defines a REST API that is intended to facilitate the collaboration of PPM and software estimation tools across the development lifecycle. The scope of this specification is defined in Use Cases. This document is the normative definition of EMS 1.0. Refer to EMS 1.0 Primer for an easy-to-read, informal description.
What is an OSLC Service?
At OSLC we use the term service in an informal way, on the assumption that members of this community have a general understanding of the term and that no confusion will arise in the absence of a formal. However, the EMS 1.0 uses service in a specific way so it is useful to define it here. The !W3C definition of a Web service gives us a starting point, but we need to modify that to incorporate the OSLC choice of REST as the architectural style and software development lifecycle collaboration as the domain. We therefore use the following working definition of service within the context of the EMS 1.0 specification:
An OSLC service is a RESTful software system designed to support interoperable lifecycle tool collaboration over the Web.
Since this definition states that an OSLC service is RESTful, we know that it must manage a set of resources that can be accessed via standard HTTP methods such as GET, POST, PUT, and DELETE. Sound software design principles tell us that a service should have good internal cohesion in the sense that the resources it manages should be closely related to each other and together serve some useful purpose. For example, if there are certain relations or data integrity constraints that must hold among resources, then it may make sense to manage those resources together in a single service. The scope of EMS 1.0 is restricted to resources that describe the estimation and measurement aspects of software projects.
On the other hand, if resources are fairly decoupled, then they should be managed by distinct services. For example, we would expect there to be distinct services for each domain of software development projects, e.g. portfolio management, project management, performance management, requirements management, change management, quality management, etc. In general a service may collaborate with many other services and applications. The REST API of each service defines the collaboration contract. This leads us to a view of larger systems being composed from webs of related OSLC services.
Organization of this Specification
The remainder of this specification is divided into the following topics:
- Architecture - describes how the EM service provider enables collaboration among PPM and software estimation tools
- Design - describes the role of RDF and the REST design choices made in this specification
- Data Model - describes the data model of each resource type and literal XML type defined in this specification
- Standard URIs - describes standard URIs for key metrics, units of measures, etc.
