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
>
AmHome
>
AMRestApiV1
(20 Jul 2010,
JimConallen
)
(raw view)
---+ Architecture Management REST API _1.0 SPECIFICATION DRAFT_ %TOC% ---++ Introduction This REST API is designed with some principals in mind. Management of resources is categorized into three areas; factory, query and resource. A factory is where resources are created. In general only a POST method is allowed on a factory URI. Query is where a client gets a collection of resources. Resource URIs are used by clients to get a specific resource, or update and delete it. Resource URIs represent the actual instances of content managed by the AM service provider. Factory and query URIs are typically published in the service specification document. ---++ Resource URIs and Methods | *URI* | *GET* | *POST* | *PUT* | *DELETE* | *Description* | | [[AmRestModelResourcesV1][AMR Factory URI]] | | Y* | N | N | The AM resource factory URL for creating new AM resources based on OSLC defined resource format. This URL is discovered in the [[AMServiceDescriptionV1][AM Service Specification Document]]. | | [[AmResourceSourceFactoryApiV1][AMR Source Factory URI]] | | Y* | N | N | The AM resource factory URL for creating new AM resources from non-OSLC defined resource formats. This URL is discovered in the [[AMServiceDescriptionV1][AM Service Specification Document]]. | | [[AmRestModelElementV1][AMR URI]] | Y | N | Y* | Y* | An AM resource identifiable with a permanent URI (permalink). | | [[AmQuerySpecV1][AMR Query URI]] | Y | Y | N | N | The simple query service, that allows clients to query for AM resources. This URL is discovered in the [[AMServiceDescriptionV1][AM Service Specification Document]]. | | [[AmDelegatedResourceSelectionCreationV1][AMR Selection URI]] | Y | N | N | N | The delegated resource selection (and creation) service. This URL is discovered in the [[AMServiceDescriptionV1][AM Service Specification Document]]. | | [[AmLinkTypeManagementV1#LinkTypeFactoryUri][Link Type Factory URI]] | Y | Y** | N | N | If the server permits, link types can be retreived and added via this URI. This URL is discovered in the [[AMServiceDescriptionV1][AM Service Specification Document]]. | | [[AmLinkTypeManagementV1#LinkTypeResourceURI][Link Type Resource URI]] | Y | N | Y** | Y** | The URI where a client can retrieve, update and delete a link type. | | [[AmLinkTypeManagementV1#LinkTypeQueryUri][Link Type Query URI]] | Y | N | N | N | The client can retrieve the set of link types already defined for this context. This URL is discovered in the [[AMServiceDescriptionV1][AM Service Specification Document]]. | * 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: <blockquote> =<?xml version="1.0" encoding="UTF-8"?><br /><rdf:RDF <br /> xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"<br /> xmlns:oslc="http://open-services.net/ns/core#"><br /><br /> <oslc:Error><br /> <oslc:statusCode>409</oslc:statusCode><br /> <oslc:message>The request to change the resource does not have the most recent ETag value.</oslc:message><br /> </oslc:Error><br /><br /></rdf:RDF>= <br /></blockquote> Another example including a reference to an HTML page with additional information and possible alternate solution to the error. <blockquote><verbatim><?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/ns/core#"> <oslc:Error> <oslc:statusCode>409</oslc:statusCode> <oslc:message>Invalid ETag value.</oslc:message> <oslc:extendedError> <oslc:ExtendedError oslc:rel="alternate" oslc:hintWidth="200px" oslc:hintHeight="200px"> <oslc:moreInfo rdf:resource="https://am.acme.com/messages?ref=a329df3aeef5543"/> </oslc:ExtendedError> </oslc:extendedError> </oslc:Error> </rdf:RDF> </verbatim></blockquote> ---++ References * [[http://www.ietf.org/rfc/rfc2616.txt][RFC2616 HTTP]]
E
dit
|
A
ttach
|
P
rint version
|
H
istory
: r25
<
r24
<
r23
<
r22
<
r21
|
B
acklinks
|
V
iew topic
|
Ra
w
edit
|
M
ore topic actions
Topic revision: r25 - 20 Jul 2010 - 15:35:55 -
JimConallen
Main
Main Web
Create New Topic
Index
Search
Changes
Notifications
RSS Feed
Statistics
Preferences
Webs
Main
Sandbox
TWiki
Български
Cesky
Dansk
Deutsch
English
Español
Français
Italiano
日本語
Nederlands
Polski
Português
Русский
Svenska
简体中文
簡體中文
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