Reporting REST API

Introduction

The purpose of the REST API is to define the implementation (low-level) details of the communication between reporting clients and the data sources.The functions covered by this section are:

• content negociation
• authentication
• error reporting and handling

Terminology

Data Source - an application/repository from which data is retrieved for reporting purposes

Schema - refers to the resource schema or data schema

Data - refers to the representation of a query result

References

Change Management REST API

Requirements Management REST API

Media types

Reporting providers and consumers should use the following media types.

Requesting Formats

This section was taken from Change Management REST API

The requiremens on the CM Specification fit in the general reporting context and adopting a common format type ensures compaitbility between OSLC initiatives.

There will be a single supported method for a client to designate it's required response format, using the HTTP request header of Accept

If only Accept header is supplied and has more than one {mime-type}, then the server will determine the {mime-type} will be used for the response content type.
If none are provided then a default is used, which is application/xml unless defined otherwise.

If the requested {mime-type} is unknown, a HTTP response code of 415 Unsupported Media Type will be returned.
Each of the operation on a given URI may support a different default {mime-type}.

Authentication

The reporting client must be able to use the following authentication protocols.

* The Form Based Authentication protocol is not standardized. To ensure the consumer and providercan work together, the "Form Based Authentication" supported by the Reporting domain should use the Java conventions:

• action: j_security_check
• user name: j_username
• password: j_password

** OAuth - this actually reffers to the communication with the OAuth consumer and is not covered by the OAuth protocol; more details about OAuth troubles here. To ensure the consumer and provider can work together, the actual authentication mechanisms supported with OAuth are:

• Basic and Digest Authentication
• Form Based Authentication with j_security_check

*** 2 Legged OAuth could be interesting in the context of Reporting but has little value for document generation.

The reporting client must be able to use both http and https transport layers.

Error Reporting

Whenever a request results in an error, a status code in the range of 400-599 is returned from the server. A service provider returns a response message body with additional information about the error. The response's body content type corresponds the requested content.

The properties in the error response MUST be defined by each domain. The error must contian but is not limited to:

• error code - unique error code per domain
• message - human readable error message

The error message text must be in the appropriate locale specified in the request.

See CM Error Status Example for an example.

Workflow

This section describes how content is retrieved from the server. The content can be Resource Schema or the representation of a query result.

Reporting Client -the tool/human reporting from the data source

Reportable API - a REST API conforming to the current specification used by the Reporting Client to access the Data Source's resources. This is used in the diagrams to emphasise that the Reporting Client is comunicating with the tool only via the Reportable REST API. However the Reportable REST API can re-use existing components such as the one for authentication, query etc.

Authentication Provider - the component of the Data Source handling authentication operations. Optional.

Data Provider - the component of the Data Source that processes Queries by collecting the data from repository and represent it according to the Resource Representation

Request Flow

Describes the generic flow of a request from the moment it is issued by the reporting client until the result or an error is returned through the Reportable API.

Succesfull Request - No Authentication

Describes the flow of a request from the moment it is issued by the reporting client until the result is returned through the Reportable API. The result type matches the media type requested by the Reporting Client. This use case if for data sources that do not require authentication.

Succesfull Request - Authentication

Describes the flow of a request from the moment it is issued by the reporting client until the result is returned through the Reportable API. The result type matches the media type requested by the Reporting Client. This use case if for data sources that require authentication.

Question: does the reporting tool need to be aware of the authentication type?

Failed Request - Authentication Error

Describes the flow of a request from the moment it is issued by the reporting client until an authentication error is returned through the Reportable API. This use case if for data sources that require authentication.

Failed Request - Request Error

Describes the flow of a request from the moment it is issued by the reporting client until an authentication error is returned through the Reportable API. This use case if for data sources that do require authentication. The reporting client needs to authenticate before its request is processed.

Comments

Add your comments here:

Suggestion to add a sequence flow of requests and response starting from requesting schema, to query, to getting back XML data, including authentications.

This would give workgroup members a end to end scenario on the request/response protocol between service provider and reporting consumer.

-- TackTong - 26 Nov 2009