Accompa REST API - Introduction |
The Accompa REST API allows customers and partners of Accompa to connect third-party applications as well as home-grown applications to Accompa. It is implemented as plain XML over HTTP using all four standard verbs (GET/POST/PUT/DELETE).
Every resource (such as Requirement, Feature, Use Case, or User) has its own URI and is manipulated in isolation. Our API closely follows the REST principles and is designed to be easy to use.
For testing out the various features that our REST API offers - we recommend that you use curl (command line), or the Firefox plugin RESTClient (graphical UI).
In this API manual, we use the following notation: |
{text}
|
Indicates text that should be replaced by your own data. |
| ... |
Indicates content from the request/response has been removed for brevity in documentation. See the specific API Request page for a full description and complete format of content. |
|
| |
Authentication |
You’re required to provide user credentials with every API request - you should provide this via HTTP Basic Authentication. Use of the API is achieved through an existing user account in Accompa - there’s no special API user. Security of your data can be achieved via SSL (i.e. using "https://" instead of "http://").
Here's an authentication example using curl: |
curl -u username:password -H "Content-Type: application/xml" \
-d "<request>...</request>" https://url |
| |
Base URI |
You construct the URI of a resource by combining a "Base URI" with the resource-specific URI (documentation for each API Request provides requisite resource-specific URI).
Here's the Base URI: |
| https://www.accompa.com/api{version}/{api_key} |
, where:
{version} is an optional integer number referring to the API version. The latest released version is "2" and is recommended for all new implementations. If you leave {version} out of the base URI, version "1" of the API will be used.
{api_key} is a unique API key for your organization; we issue this to you when you register with us to enable API access for your account. |
| |
How to Read Using REST API
|
Reading a resource is achieved via a HTTP GET request to the appropriate URI. This will return HTTP status code 200, and an XML response containing the data, if successful. If nothing is found, an HTTP 404 "not found" response will be returned.
Here's an example using curl to read a Requirement whose ID is "55" (i.e. "RE-55" in your Accompa account): |
| GET Example - Read Requirement |
| curl -u username:password https://www.accompa.com/api2/{api_key}/re/55 |
| In the above example - if a requirement with ID "55" exists, an XML response will be generated along with the status code "200". The XML response will contain the data stored for that particular Requirement (i.e. "RE-55"). If nothing is found, the response HTTP 404 "not found" will be returned. |
| |
How to Write Using REST API
|
To create or update resources, you'll be sending XML data into Accompa. Remember to add the header "Content-type: application/xml" to indicate that XML data is coming in. Then simply include the XML of the resource in the body of your request, and you’re done.
Creating a resource is done using the POST verb. A successful creation responds with HTTP status code "201" - with the Location header set to the URI of the newly created resource.
Here's an example using curl to create a Requirement: |
| POST Example - Create Requirement |
curl -u username:password -H "Content-Type: application/xml" \
-d "<requirement>...</requirement>" \
-X POST https://www.accompa.com/api2/{api_key}/re |
| This creates a new requirement, with the authenticated user as creator.
It's often easier to have the XML fragment in a file rather than type it into the command line, you can do this using curl as shown below: |
| POST Example - Create Requirement - Using a File |
curl -u username:password -H "Content-Type: application/xml" \
-d @requirement.xml -X POST https://www.accompa.com/api2/{api_key}/re |
| , where the content of the requirement.xml file could be as follows: |
<requirement>
<fields>
<field>
<name>field_49</name>
<value>This is my Title.</value>
</field>
<field>
<name>field_50</name>
<value>This is my Description.</value>
</field>
<field>
<name>field_51</name>
<value>3</value>
</field>
</fields>
</requirement> |
Updating a resource is done using the PUT verb. The response to a successful update is "200".
Here's an example using curl to update the "Owner" field of a Requirement with ID of "55" (i.e. "RE-55"): |
| PUT Example - Update Requirement |
curl -u username:password -H "Content-Type: application/xml" \
-d @requirement.xml -X PUT https://www.accompa.com/api2/{api_key}/re/55 |
| , where the content of the requirement.xml file could be as follows: |
<requirement>
<fields>
<field>
<name>field_63</name>
<value>3</value>
</field>
</fields>
</requirement> |
| In the above example - if a requirement with ID "55" exists (i.e. "RE-55"), it will be updated and the status code "200" will be returned. If "RE-55" is not found, the response HTTP 404 "not found" will be returned. |
| |
How to Delete Using REST API
|
Deleting a resource is done using the DELETE verb. The response to a successful deletion is "200".
Here's an example using curl to delete a Requirement with ID of "55" (i.e. "RE-55"): |
| DELETE Example - Delete Requirement |
| curl -u username:password
-X DELETE https://www.accompa.com/api2/{api_key}/re/55 |
| We hope you found this page helpful in getting a good overview of how to use the Accompa REST API. For further details about specific API requests, please click the desired API request in the "Table of Contents" to the right. |
| |
API Usage Rate Limits |
| To maintain optimum performance and ensure that the Accompa API is available to all of our customers, we impose API usage rate limits. This is explained in detail here - please follow these guidelines while programming your client to ensure your account is not inadvertently blocked. |
