The AMSUWL API (BETA!)

Introduction

The AMSUWL API is in Beta right now, so if you have any issues at all with it, please let us know and we'll get it fixed ASAP.

The AMSUWL API is very similar to the Highrise API, if you're familiar with that. It follows the REST principles as closely as possible, with each resource (User, Site, Client) having its own url and being accessed/changed in isolation.

You can explore the view part of the API (everything that's fetched with GET) through a regular browser. Pretty much any URL in AMSUWL can be viewed in XML by adding the .xml extension, while authenticated as a valid User.

Authentication

The API token is directly tied to a user, so when you log in as a particular user over the API, you can only see and modify anything that they'd normally have access to. Authenticating is done with an authentication key. To get yours, click on Settings, then User Settings, and look for the API Key section. There, you can access, generate and delete your API Key. Abuse of the API Key will result in the API key being revoked.

When using the API Key, you don't need a separate password. But since AMSUWL uses HTTP Basic Authentication, and lots of implementations assume that you want to have a password, it's often easier just to pass in a dummy password, like X.

Example using the API Key and a dummy password through curl:

curl -u 605b32dd:X http://amsuwl.com/users/1.xml

Remember that anyone who has your API Key can see and change everything you have access to. You can re-generate it at any time from your Settings page if you need to.

Reading through the API

The AMSUWL API has two categories of actions for reading: Show and list. Show returns a single record and list returns a collection.

A few examples of reading with curl:

curl -u 7T8srdvueEJjluMGzTLNwJr5KDLDXfKntw7MMzZx:X http://amsuwl.com/clients/5.xml
curl -u 7T8srdvueEJjluMGzTLNwJr5KDLDXfKntw7MMzZx:X http://amsuwl.com/sites.xml

If the read is successful, you'll get an XML response back along with the status code "200 OK".

Writing through the API

When you're creating and updating resources, you'll be sending XML into AMSUWL. You need to let the system know that fact by adding the header "Content-type: application/xml", so we know that it's not regular form-encoded data coming in. This is very important. Then you just include the XML of the resource in the body of your request. Since web browsers only support GET and POST, your implementation may require that the PUT and DELETE verbs be supplied via a form variable called '_method' with the corresponding 'put' or 'delete' value.

Here's an example of how you'd create a new user.

curl -u 7T8srdvueEJjluMGzTLNwJr5KDLDXfKntw7MMzZx:X -H 'Content-Type: application/xml' \
-d '<user><email>bob@dole.com</email><password>8888888</password><password_confirmation>8888888</password_confirmation><first_name>Bob</first_name><last_name>Dole</last_name></user>' http://amsuwl.com/users.xml

The response to a successful creation is the status code "201 Created". You can get the URL of the new resource in the Location header (such that you know where to update your new resource in the future). We also include the complete XML for the final resource in the response. This is because you can usually create a new resource with less than all its regular attributes.

Updating resources is done through the PUT verb and against the URL of the resource you want to update. Here's an example:

curl -u 7T8srdvueEJjluMGzTLNwJr5KDLDXfKntw7MMzZx:X -X PUT -H 'Content-Type: application/xml' \
-d '<user><email>bobsnewemail@dole.com</email></user>' http://amsuwl.com/users/5.xml

The response to a successful update is "200 OK".

Finally, you can delete resources (if you're allowed to) using the DELETE verb. A few examples of that:

curl -u 7T8srdvueEJjluMGzTLNwJr5KDLDXfKntw7MMzZx:X -X DELETE http://amsuwl.com/users/5.xml
curl -u 7T8srdvueEJjluMGzTLNwJr5KDLDXfKntw7MMzZx:X -X DELETE http://amsuwl.com/users/5.xml

Note that you don't need to pass the content-type header because you're not sending any XML. The response to a successful delete is "200 OK".

Dealing with failure

If a request fails, the error information is returned with the HTTP status code. For instance, if a requested record could not be found, the HTTP response might look something like:

HTTP/1.1 404 The record could not be found
Date: Thu, 16 Mar 2006 17:41:40 GMT
...

Note that, in general, if a request causes a new record to be created (like a new message, or to-do item, etc.), the response will use the "201 Created" status. Any other successful operation (like a successful query, delete, or update) will use a 200 status code.