Architecture Management REST API
1.0 SPECIFICATION DRAFT
Introduction
Architecture Management resources represent a wide variety of artifacts, created and edited by various tools.
The intent of this specification is to define the set of HTTP-based RESTful interfaces in terms of HTTP methods: GET, POST, PUT and DELETE, HTTP response codes, mime type handling and resource formats.
The resource formats and operations may not match exactly the native models supported by architecture (model) management service providers but are intended to be compatible with them. The approach to supporting these scenarios is to delegate operations, as driven by service provider contributed user interfaces, as much as possible and not require a service provider to expose its complete data model and application logic.
Since the actual storage formats of the model elements themselves remain the scope of the individual AM tools, it is possible to distill common properties and provide access to them through this REST API.
Resource URIs and Methods
* not all resource types are supported.
** service providers MAY permit the modification of link types
Authentication
OSLC Services use standard web protocols for authentication. OSLC Services can use HTTP Basic Authentication, OAuth or both.
HTTP Basic Authentication
OSLC Services
MAY protect resources with HTTP Basic Authentication. OSLC Services that use HTTP Basic Authentication
SHOULD do so only via SSL.
OAuth Authentication
OSLC Services
MAY protected resources with OAuth Authentication.
Form Based Authentication
OSLC Services
MAY use other authentication mechanisms, including those common described as Form Based Authentication. OSLC Services that choose to use other authentication mechanisms are responsible for specifying how those mechanisms work.
Error Status Information
Whenever an HTTP 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 body containing additional information about the error. The response's body media type MUST be application/rdf+xml, with the following properties defined in the
http://open-services.net/xmlns/common/1.0 namespace:
- oslc:statusCode - required element containing HTTP status code corresponding to this request (this is a replication of the code in the response status line).
- oslc:message - required element containing an error message string suitable for presentation to a user of the client
- oslc:url - optional element whose string content is a URL indicating a Web presentation giving more information on the error
- oslc:rel - optional attribute with value of "alternate" indicating that it is an alternate method to resolve the error
- oslc:hintWidth - optional attribute
- oslc:hintHeight - optional attribute
Implementations MAY provide additional properties. The error message text SHOULD be appropriate to the locale of the requesting client.
Examples
In
application/rdf+xml
format:
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:oslc="http://open-services.net/xmlns/common/1.0/">
<oslc:Error>
<oslc:statusCode>409</oslc:statusCode>
<oslc:message>The request to change the resource does not have the most recent ETag value.</oslc:message>
</oslc:Error>
</rdf:RDF>
Another example including a reference to an HTML page with additional information and possible alternate solution to the error.
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:oslc="http://open-services.net/xmlns/common/1.0/">
<oslc:Error>
<oslc:statusCode>409</oslc:statusCode>
<oslc:message>The request to change the resource does not have the most recent ETag value.</oslc:message>
<oslc:url oslc:rel="alternate" oslc:hintWidth="200px" oslc:hintHeight="200px">
https://am.acme.com/messages?ref=a329df3aeef5543
</oslc:url>
</oslc:Error>
</rdf:RDF>
References
Back to
Architecture Management Home
Comments
Enter your comments here.