ReportingRESTApi < Main

This wiki is locked. Future workgroup activity and specification development must take place at our new wiki. For more information, see this blog post about the new governance model and this post about changes to the website.

TWiki>

Main Web>MainOslcCommonArchitecture>ReportingHome>ReportingRESTApi (15 Mar 2010, DragosCojocari) (raw view)

---+ Reporting REST API

%TOC%
---++ 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 [[ReportingResourceSchema][resource schema]] or data schema

Data - refers to the [[ResourceFormat][representation]] of a [[ResourceQuery][query]] result
---++ References

[[http://open-services.net/bin/view/Main/CmRestApiV1][Change Management REST API]]

[[http://open-services.net/bin/view/Main/RmRestApiV1][Requirements Management REST API]]

---++ <a name="MediaType" title="MediaType"></a> Media types

Reporting providers and consumers should use the following media types.

| *Media Type* | *Defined* | *Response* |
| application/xml | [[http://www.w3.org/TR/xml/][W3C Extensible Markup Language (XML)]] | [[ResourceFormat][Resource Representation]] |
| text/html | [[http://www.w3.org/TR/xml/][W3C Extensible Markup Language (XML)]] | [[ResourceFormat][Resource Representation]] |
| application/atom+xml | [[http://tools.ietf.org/html/rfc4287][RFC4287 - Atom Syndication Format]] | [[ResourceFormat][Resource Representation]] |
| none | - | [[ResourceFormat][Resource Representation]] |
| other? | is this required? | |

---++ Requesting Formats

This section was taken from [[http://open-services.net/bin/view/Main/CmRestApiV1?sortcol=table;up=#Requesting_Formats][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.
<blockquote>

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.<br />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.<br />Each of the operation on a given URI may support a different default {mime-type}.
</blockquote>

---++ Authentication

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

| *Authentication* |
| [[http://tools.ietf.org/html/rfc2617][Basic and Digest Authentication]] |
| [[http://onjava.com/pub/a/onjava/2002/06/12/form.html][Form Based Authentication with j_security_check]] * |
| [[http://oauth.net/][3 legged OAuth]] ** |
| [[http://open-services.net/bin/view/Main/OAuthenticationTroubles#2_Legged_OAuth][2 legged OAuth ?]] *** |

* 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 [[OAuthentication troubles][here]]. To ensure the consumer and provider can work together, the actual authentication mechanisms supported with OAuth are:
   * [[http://tools.ietf.org/html/rfc2617][Basic and Digest Authentication]]
   * [[http://onjava.com/pub/a/onjava/2002/06/12/form.html][Form Based Authentication with j_security_check]]

<strong>***</strong> [[http://open-services.net/bin/view/Main/OAuthenticationTroubles#2_Legged_OAuth][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://tools.ietf.org/html/rfc2616][http]] and [[http://tools.ietf.org/html/rfc5246][https]] transport layers.
---++ Error Reporting

Whenever a request results in an error, a status code in the range of [[http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html][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 [[http://open-services.net/bin/view/Main/CmRestApiV1?sortcol=table;table=up#Error_status_examples][CM Error Status Example]] for an example.

---++ Workflow

This section describes how content is retrieved from the server. The content can be [[ReportingResourceSchema][Resource Schema]] or the [[ResourceFormat][representation]] of a [[ResourceQuery][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 [[ResourceQuery][Queries]] by collecting the data from repository and represent it according to the [[ResourceFormat][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.

<img alt="Data_Request.png" src="%ATTACHURL%/Data_Request.png" />

---+++ 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 [[#MediaType][media type]] requested by the Reporting Client. This use case if for data sources that do not require authentication.

<img alt="Successfull_request_-_no_authentication.png" src="%ATTACHURL%/Successfull_request_-_no_authentication.png" />

---+++ 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 [[#MediaType][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?

<img alt="Successfull_request_-_authentication.png" src="%ATTACHURL%/Successfull_request_-_authentication.png" />

---+++ 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.

<img alt="Failed_request_-_authentication_error.png" src="%ATTACHURL%/Failed_request_-_authentication_error.png" />

---+++ 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.

<img alt="Failed_request_-_request_error.png" src="%ATTACHURL%/Failed_request_-_request_error.png" />
---++ 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.

-- Main.TackTong - 26 Nov 2009 
%COMMENT%

Attachments

Topic attachments
I	Attachment	Action	Size	Date	Who
png	Data_Request.png	manage	26.9 K	07 Dec 2009 - 11:04	DragosCojocari
png	Failed_request_-_authentication_error.png	manage	10.0 K	14 Dec 2009 - 13:22	DragosCojocari
png	Failed_request_-_request_error.png	manage	20.4 K	14 Dec 2009 - 13:22	DragosCojocari
png	Successfull_request_-_authentication.png	manage	20.5 K	14 Dec 2009 - 13:22	DragosCojocari
png	Successfull_request_-_no_authentication.png	manage	7.3 K	14 Dec 2009 - 13:22	DragosCojocari

Topic revision: r14 - 15 Mar 2010 - 11:04:25 - DragosCojocari

Main.ReportingRESTApi moved from Main.Authentication on 23 Nov 2009 - 12:24 by DragosCojocari - put it back

Main

Webs
Main
Sandbox
TWiki

Copyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use
Ideas, requests, problems regarding this site? Send feedback