API - Introduction

The Vitalist API utilizes simple XML over HTTP conforming to REST principles as much as possible. You can get, add, edit, and delete all of your actions, projects, contacts, and contexts via the Vitalist API. In addition, all requests can return results in the format of your choice by simply changing the file extension.

Vitalist currently supports the following data formats: XML and JSON.

Authentication

Vitalist API methods require both a key for the requesting application, and an API key for the Vitalist user. All requests to the API are in the context of that authenticated user.

Currently, HTTP Basic Authentication is the only supported authentication scheme. When authenticating with HTTP Auth, the application’s key is the username component, while the Vitalist user’s API key is the password.

Help

The best way to get help regarding the API is to visit our forum. Feel free to ask questions, suggest improvements, and even collaborate on projects. You may also email us at support@vitalist.com.

Reading data from Vitalist

Retrieving data from Vitalist is achieved by using a simple GET request. Here is an example using curl:

curl -u {app_key}:{api_key} http://www.vitalist.com/services/api/actions.xml

Adding, editing, and deleting data

Adding, editing, and deleting data is just as easy. Simply add an XML formatted string to your request detailing what you want to do with your data. Here is an example using curl:

curl -u {app_key}:{api_key} -X POST -H ‘Content-Type: text/xml’ -d ‘<request><actions><action><body>new action</body></action></actions></request>’ http://www.vitalist.com/services/api/actions.xml

Notice the ‘Content-Type’ header added in the request. When sending XML data in your request, the ‘text/xml’ content type is required.

Responses from Vitalist

Responses from Vitalist API requests can be retrieved in either XML or JSON formats. All responses will include a status code and message, along with the data requested. Any errors will be returned with the appropriate status along with an error message.

Example successful response:

<response>
   <statusCode>200</statusCode>
   <message>Ok</message>
   <actions>
      <action>
         …
      </action>
   </actions>
</response>

Example response error:

<response>
   <statusCode>400</statusCode>
   <message>Bad request</message>
</response>

Status codes:

  • 200: Ok
  • 201: Created
  • 400: Bad Request
  • 401: Unauthorized
  • 500: Internal Server Error

More Details

More details for each method can be found here: Actions, Projects, Contacts, Contexts, and Users.