4.6. S-RAMP REST API

This section describes the API for REST clients that are written by the users. These are different than the S-RAMP shell and user interface shipped with JBoss Enterprise SOA Platform 6.
The S-RAMP specification outlines a data model and protocol that define how a repository should store and manipulate artifacts. The S-RAMP specification does not dictate the format of the Atom REST endpoints. Instead, the client is expected to query a service document endpoint and inspect it to find the various relevant endpoints. The specification does present a notional format, but implementations are not required to follow it. In general, the Atom API data models are used to wrap custom S-RAMP specific XML structures.

4.6.1. Atom Entry Document

Atom Entry documents are used when dealing with individual artifacts.
The Atom entry document is the Atom representation of an S-RAMP artifact object. There are two Atom representations of an S-RAMP artifact object:
  • A summary Atom entry that appears in an Atom feed document. Summary entries do not include the S-RAMP structured extension element (S-RAMP foreign markup).
  • A complete Atom entry which includes the S-RAMP structured extension element.

4.6.2. Atom Feed Document

A feed in S-RAMP is XML data which contains Atom entries. S-RAMP defines several Atom feeds which are used to access fine-grained support for relationships.
An Atom Feed Document is a representation of an Atom feed. It includes metadata about the feed, and the entries associated with it. Use Atom Feed documents when dealing with lists of documents.

4.6.3. Adding Artifacts

From the protocol standpoint, S-RAMP provides two types of artifacts:
  • Document Style Artifacts
    These artifacts are based on files or binary content. For the document style artifacts, the client must POST the binary content to the correct Atom Endpoint.
  • Logical Artifacts
    These artifacts are direct instantiation artifacts. For the logical artifacts, there is no document content and the client must POST an Atom Entry containing an S-RAMP artifact XML entity to the appropriate endpoint. If successful, the server responds with an Atom Entry containing the full meta data of the newly created artifact.
You can add one of these artifacts using the POST request as shown below: 
POST /s-ramp/{model}/{type}

4.6.4. Updating Artifacts

A client can update the artifact metadata such as properties, classifiers, and relationships. You can update artifacts using the PUT request as shown below to the endpoint of an artifact: 
PUT /s-ramp/{model}/{type}/{uuid}
You can find the endpoint of an artifact either by querying for the artifact or as part of the Atom Entry returned when the artifact was created.

4.6.5. Deleting Artifacts

A cient can delete an artifact by performing a DELETE request to the endpoint of an artifact as shown below: 
DELETE /s-ramp/{model}/{type}/{uuid}

4.6.6. S-RAMP Queries

4.6.6.1. Running an S-RAMP Query

Running an S-RAMP query means issuing a GET or POST to the S-RAMP query endpoint. S-RAMP provides full feed for all Artifact Models and Artifact Types. In both the cases, the response is an Atom Feed where each Entry provides summary information about an artifact in the respository.
Only a subset of the core properties, such as name and description, are mapped to the Atom Entry in a feed. To retrieve full details such as custom properties, classifiers, and relationships about a given entry in a feed, the client must issue an additional GET request.

4.6.6.2. S-RAMP GET and POST Query Parameters

A client can query S-RAMP by performing either GET or POST to the following notional endpoint: 
GET /s-ramp
S-RAMP supports the following parameters for GET and POST:

Table 4.9. GET/POST Query Parameters

Parameter Description
query The S-RAMP query.
startPage The page to start from.
startIndex The index number to start from.
count The number of artifacts to return.
orderBy The sort order to use when creating the feed.
ascending The sort direction to use when creating the feed.
propertyName Additional custom property to return for each artifact in the feed. You can include this property multiple times.

4.6.6.3. S-RAMP Feeds Parameters

When retrieving a simple model or type feed, the client must issue a GET request to the appropriate model or type endpoint as shown below: 
GET /s-ramp/{model}
GET /s-ramp/{model}/{type}
S-RAMP supports the following parameters for retrieving feeds:

Table 4.10. S-RAMP Feeds Parameters

Parameter Description
startPage The page to start from.
startIndex The index number to start from.
count The number of artifacts to return.
orderBy The sort order to use when creating the feed.
ascending The sort direction to use when creating the feed.
propertyName Additional custom property to return for each artifact in the feed. This property can be included multiple times.

4.6.6.4. Retrieving Full Metadata for an Artifact

In order to retrieve the full metadata for an artifact, the client must issue a GET request to the appropriate artifact endpoint as shown below: 
GET /s-ramp/{model}/{type}/{uuid}
This is necessary after a query or feed, when only the summary information is available. The summary information found in a feed or query response contains the UUID of the artifact, as well as a URL to the endpoint needed to retrieve the full artifact details.

4.6.6.5. Batch Changes to S-RAMP Archives

The batch processing function is a powerful additional feature of the S-RAMP API. The batch processing endpoint allows the client to POST an S-RAMP package, which can contain multiple Atom Entries and binary files. The package allows a client to add, update, and delete multiple artifacts in a single batch.