Root Workspace List and Search
Using the HTTP AtomPub API
Tcat Server takes advantage of the simple but powerful Atom Publishing Protocol for much of its integration API. It is a RESTful HTTP-based API based on the concept of collections and entries. AtomPub collections can store anything. The Tcat Server API uses Atom entries to represent artifacts inside the Tcat Server registry (repository). Through the Atom Publishing Protocol, new items can be created, updated, and deleted.
Important Feed URLs
Tcat Server includes the following feeds:
Feed | URL |
---|---|
{{[http://host/api/registry]}} |
|
Workspace Listing |
{{[http://host/api/registry/]` <workspacePath>}} |
Child Workspaces |
{{[http://host/api/registry/] <workspacePath>;workspaces}} |
Artifact Versions |
{{[http://host/api/registry/] <workspacePath>/<item>;history}} |
Comments |
{{[http://host/api/comments] }} |
Artifacts as Atom Entries
Each feed listed above contains a series of Atom entries that represent artifacts inside the repository. An artifact might look like this:
<entry>
<link href="/api/registry/Default%20Workspace/hello.wsdl;atom" rel="edit" />
<id>urn:galaxy:artifact:local$720ea69f-14ac-44ac-8171-1e4de567a098</id>
<title type="text">hello.wsdl</title>
<updated>2008-10-31T21:16:16.272Z</updated>
<author>
<name>Galaxy</name>
</author>
<summary type="xhtml">This is a description of the WSDL</summary>
<artifact-info xmlns="http://galaxy.mule.org/1.0"
mediaType="application/xml"
documentType="{http://schemas.xmlsoap.org/wsdl/}definitions"
created="2008-10-31T21:16:16.272Z" name="hello.wsdl" />
<version xmlns="http://galaxy.mule.org/1.0"
label="0.1"
enabled="true"
default="true"
created="2008-10-31T21:16:16.272Z" />
<metadata xmlns="http://galaxy.mule.org/1.0" id="versioned">
<property name="wsdl.binding.dependencies" locked="true" visible="true">
<value>{http://mule.org/hello_world}HelloWorldBinding</value>
</property>
<property name="wsdl.binding" locked="true" visible="true">
<value>HelloWorldBinding</value>
</property>
<property name="wsdl.service" locked="true" visible="true">
<value>HelloWorldService</value>
</property>
<property name="wsdl.targetNamespace" locked="true" visible="true" value="http://mule.org/hello_world" />
<lifecycle property="primary.lifecycle" name="Default" phase="Created">
<next-phases>Developed</next-phases>
<previous-phases />
</lifecycle>
<property name="wsdl.endpoint" locked="true" visible="true">
<value>SoapPort</value>
</property>
<property name="wsdl.portType.dependencies" locked="true" visible="true">
<value>{http://mule.org/hello_world}HelloWorld</value>
</property>
</metadata>
<metadata xmlns="http://galaxy.mule.org/1.0" id="global" />
<collection xmlns="http://www.w3.org/2007/app" id="versions" href="/api/hello.wsdl;history">
<atom:title xmlns:atom="http://www.w3.org/2005/Atom" type="text">Artifact Versions</atom:title>
</collection>
<content type="application/xml" src="/api/registry/Default%20Workspace/hello.wsdl" />
<link href="/api/registry/Default%20Workspace/hello.wsdl" rel="edit-media" />
</entry>
Walking through this Atom entry, there are a few important things to note:
-
The
<collection>
element with theid="versions"
attribute provides a link to the version history of the artifact. -
To see the actual artifact, use the link provided in the
<content>
element. -
The summary maps to the description field on the artifact.
-
The
<metadata>
sections represent metadata associated with this artifact.-
The
<metadata>
with theglobal
ID represents metadata associated with all versions of an artifact. -
The
<metadata>
with theversioned
ID represents metadata associated with this particular version. -
Lifecycle properties are represented by the
<lifecycle>
element. -
If the property is a multivalued property, there will be child
<value>
elements. If it is single valued, there will be avalue
attribute. -
If the property has the
locked
attribute set to true, it has been created by an index and cannot be modified unless it is by the index.
-
Artifact History Feeds
An item’s history can be viewed by appending ;history
to its URL. For example, if this is the artifact URL:
http://localhost:9002/api/registry/Services/hello.wsdl
The history URL is:
http://localhost:9002/api/registry/Services/hello.wsdl;history
The history URL returns a feed that contains Atom entries for each artifact version like those described in the previous section.
Using the Libraries
To use the AtomPub API with your Java application, we recommend using the Apache Abdera framework. Other tools like wget
will work as well. For a more visual guidance, check out the lnk:http://www.xucia.com/#RestTest[RestTest]FireFox plug-in.
For a more in-depth example using Abdera, see the AtomPub API Example.
Artifact Operations
The following table summarizes the operations that can be performed on the AtomPub API.
HTTP Verb | URL | Data | Description |
---|---|---|---|
GET |
/api/registry |
None |
Gets all the artifacts in the repository |
GET |
/api/registry/WORKSPACE |
None |
Gets an Atom feed of the artifacts and workspaces inside the workspace |
GET |
/api/registry/WORKSPACE;atom |
None |
Gets an Atom entry representation of the workspace |
GET |
/api/registry/WORKSPACE/ARTIFACT |
None |
Gets an artifact |
POST |
/api/registry/WORKSPACE |
An artifact |
Add a new artifact. See below for details. |
POST |
/api/registry/WORKSPACE;workspaces |
A workspace Atom entry |
Creates a new workspace. See below for details. |
PUT |
/api/registry/WORKSPACE/ARTIFACT |
An artifact |
Adds a new version of an artifact. See below for details. |
PUT |
/api/registry/WORKSPACE/ITEM;atom |
An Atom representation of an artifact |
Updates an artifact’s metadata in the registry |
DELETE |
/api/registry/WORKSPACE |
An artifact or workspace |
Deletes an artifact or workspace |
Browsing the Repository
This section describes how you can browse the repository through query parameters or URL encoding.
Querying the Repository
You can extend a URL with a query parameter to search the repository. Following are some example queries.
URL Encoding
If you are using Abdera for your client code, the handy org.apache.abdera.i18n.text.UrlEncoding
class has an encode method that can do this for you:
import org.apache.abdera.i18n.text.UrlEncoding;
import org.apache.abdera.i18n.text.CharUtils.Profile;
String encodedQuery = UrlEncoding.encode("select artifact where ...", Profile.PATH.filter());
Note: If you’re using Abdera 0.3.0, you must use the EncodingUtil.sanitize()
method instead.
For a reference on which characters must be URL-encoded, see this page.
Replace any of these characters in your query with the appropriate encoded character. For instance, if you were encoding "select artifact", you would replace the space with %20
, as that is the URL-encoded representation of the space character.
Adding an Artifact
When you add an artifact, you must supply additional HTTP headers that specify the workspace and artifact version:
-
The "X-Artifact-Version": the version label of the artifact you are POSTing.
-
The "Slug" header: used to determine the name of the artifact in the repository.
A typical HTTP POST looks like this:
POST /api/registry/WORKSPACE HTTP/1.0
Authorization: Basic YWRtaW46YWRtaW4=
Host: localhost:8080
Content-Type: text/plain
X-Artifact-Version: 1.0
Slug: test.txt
Here’s an example using wget
:
$ wget --post-file=YOURFILE --http-user=admin --http-password=admin -S \
--header="X-Artifact-Version: 0.1" \
--header="Slug: ARTIFACT_NAME"
http://localhost:8080/api/registry/Default%20Workspace
Adding a New Artifact Version
Adding a new artifact version is very similar to adding a new artifact, with the following exceptions:
-
Use the PUT verb
-
Use the URL of the artifact in the repository
-
Specify an X-Artifact-Version header
For example:
PUT /api/registry/WORKSPACE/ARTIFACT HTTP/1.0
Authorization: Basic YWRtaW46YWRtaW4=
Host: localhost:8080
Content-Type: text/plain
X-Artifact-Version: 0.2
... data ...
Adding a Workspace
To add a workspace, post an Atom entry that represents the workspace to the parent workspace. For example:
POST /api/registry/Default%20Workspace;workspaces HTTP/1.0
Authorization: Basic YWRtaW46YWRtaW4=
Host: localhost:8080
Content-Type: application/atom+xml;type=entry
<entry xmlns="http://www.w3.org/2005/Atom">
<title type="text">MyNewWorkspace</title>
<updated>2015-08-10T01:12:38.758Z</updated>
<author>
<name>Ignored</name>
</author>
<id>urn:uuid:8D931B8E837772B5521204074758762</id>
<content type="text"></content>
</entry>
This creates a new workspace called "MyNewWorkspace" in the parent workspace "Default Workspace".
To add a top-level workspace, POST to /api/registry
. This workspace then is listed in /api/registry;workspaces
.
Editing an Artifact’s Metadata
To edit an artifact’s metadata, PUT a new Atom entry representation to the artifact URL. You can update the artifact’s description, metadata, and lifecycle information.
For example, you could use this HTTP request to update the description of your artifact:
PUT /api/registry/Default%20Workspace/hello.wsdl;atom HTTP/1.0
Authorization: Basic YWRtaW46YWRtaW4=
Host: localhost:8080
Content-Type: application/atom+xml;type=entry
<entry xmlns="http://www.w3.org/2005/Atom">
<link href="/api/registry/Default%20Workspace/hello_world.wsdl;atom?version=0.2" rel="edit" />
<id>urn:galaxy:artifact:50d245b3-8855-4d4d-83f6-2351ae0b23b6:0.2</id>
<title type="text">hello_world.wsdl Version 0.2</title>
<updated>2015-08-10T00:57:07.116Z</updated>
<author>
<name>Galaxy</name>
</author>
<summary type="xhtml">
This becomes your new artifact description.
</summary>
<content type="application/xml" src="/api/registry/Default%20Workspace/hello_world.wsdl?version=0.2" />
<link href="/api/registry/Default%20Workspace/hello_world.wsdl?version=0.2" rel="edit-media" />
</entry>
Note: You must PUT it to the Atom representation, which means you must append ;atom
to the URL.
To edit an artifact’s metadata, you include a <metadata>
element inside your Atom entry. Any <property>
elements inside this element are modified. In the following example, the property favoriteSauce
is added to the artifact with a value of ketchup
.
<entry>
...
<metadata id="versioned" xmlns="http://galaxy.mule.org/1.0">
<property name="favoriteSauce" value="ketchup"/>
</metadata>
...
</entry>
Any metadata properties that are not present are NOT deleted. To delete a metadata property, remove all value attributes and child elements:
<metadata id="versioned" xmlns="http://galaxy.mule.org/1.0">
<property name="propertyToDelete" />
</metadata>
Next: AtomPub API Example >>