Skip to main content
All CollectionsAssembla BasicsLearn More
Getting Started with Assembla Developer API
Getting Started with Assembla Developer API
Toshi Dávila avatar
Written by Toshi Dávila
Updated over 4 years ago

Terminology

The terminology we use is from Oauth2 draft in addition to Assembla terminology.

  • a Client is your application registered on the Assembla site; you will use the ID and secret to identify the application you want to generate access tokens for.

  • Access Tokens are used to generate user sessions. Tokens have a 15 minutes timeout which resets when the token is used. If an access token is expired, you can use a refresh token to generate a new one without authentication.

  • Refresh Tokens are used to generate new access tokens without asking authentication from users. Refresh tokens have a 31 day timeout which resets when the token is used.

  • Bearer Tokens are security tokens. Any party in possession of the token (a “bearer”) can use the token in any way that any other party in possession of it can.

Application registration

To start using the API, first register a client. A client is your application registered on the Assembla site; you will send the ID and secret with basic authentication in your authorization requests to identify the application you want to generate access tokens for.

You will be asked to fill three fields in order to register your app:

  • Name - a user defined name that will identify the application (required).

  • Website URL - The URL to the application web site.

  • Redirect URL - the callback URL on your application; users will be redirected here with an access token or an authorization code. Usable for web services only. If you plan to use Web service flow authentication be sure to fill this field out, otherwise you will get an error.

Caution! Sharing your client ID and secret can give someone else the ability to generate access tokens for your application and authenticate requests you may not want, keep them safe.

Overview

Assembla Developer API provides resources to be used by external applications, using a secure authentication mechanism (OAuth 2) and based on REST architecture.

Start with your application

After a client is created, you are able to generate access tokens and authenticate user sessions. To generate an access token visit the authentication documentation page.

Resources and URL schema

The API is accessible at https://api.assembla.com
API resources reside in the /api URL namespace. A typical API resource can be fetched at: https://api.assembla.com/_version/path/to/resource

HTTP Verbs

List of HTTP verbs for the Assembla API with a response status:

GET Retrieve an array of resources or an identified resource.

POST Create a resource.

PUT Update an identified resource. PUT requests do not return any body in responses, to get the body of the updated object request with GET to the same URL.

DELETE Delete and identified resource.

Authentication

Assembla uses Oauth2 to authenticate users from external applications, available authentication flows are.

  1. Web service suitable for browser based applications.

  2. Client credentials suitable for applications that rely on public data and do not require user authentication.

  3. Pin Code suitable for desktop/mobile applications.Refresh token not strictly an authorization flow, using refresh tokens you can generate new access tokens without authenticating again with available refresh tokens.

Any authentication flow will return a bearer access token. To authenticate your requests to API resources add the Authorization: Bearer \_tokenHTTP header to your request headers list.

Requests

A request to an API resource should include:

Required:

  1. Authorization: Bearer _your_token HTTP header;

  2. .xml or .json termination of URLs to identify data type you want to request from the server;

  3. Client ID and secret sent via basic authentication;

Consider requesting JSON instead of XML, because JSON is much faster.

Conditional:

  1. Content-type: application/(xml,json) header, data can be presented to server in three formats: query string(no Content-type), application/xml, application/json;

  2. Body data type should be sent based on Content-type HTTP header i.e. Content-type header is set to application/xml you have to send an XML body, application/json for JSON. If no Content-type is set, data should be a query string

Example request, using cURL utility

$ curl -H "Authorization: Bearer 9c04c84ea5e85d5aaa788ac74af60d3f" -u "dtE8rqjW8r4yJWadbNA33N:4bfc7bbab6cc34aa38f2297a1d12465f" https://api.assembla.com/v1/spaces/test-1/tickets.json

  • Bearer access token: 9c04c84ea5e85d5aaa788ac74af60d3f

  • Client ID: dtE8rqjW8r4yJWadbNA33N

  • Client secret: 4bfc7bbab6cc34aa38f2297a1d12465f

You can use only HTTPS on API requests; HTTP requests will be redirected to HTTPS.

NOTE: Assembla will accept only UTF-8 and UTF-8 compliant data, please make sure your data is encoded correctly.

Responses

Things you must pay attention to in API responses:

  • HTTP Status header, result of the operation, check the Statuses and Errors section for more info;

  • Content-type, body data type requested in API request;

  • Location HTTP header, POST operations only, the URL of newly created resource;

  • Response body, not present on PUT operations, data body formatted as requested.

Example XML response:

HTTP/1.1 200 OK
Server: nginx/0.8.55
Date: Tue, 12 Jun 2012 12:14:24 GMT
Content-Type: application/xml; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Status: 200
...

<?xml version="1.0" encoding="UTF-8"?>
...

Example JSON response:

HTTP/1.1 200 OK
Server: nginx/0.8.55
Date: Tue, 12 Jun 2012 12:16:06 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Status: 200
...

[...]

Note: Some response bodies are paginated, in this case page and per_page parameters are available where maximum value for per_page is 100, bigger values will be ignored and set to 10. Follow request documentation to find out if pagination is available.

Statuses and Errors

Statuses on success:

  • 200 OK Success from a GET, PUT or DELETE operation;

  • 201 Created Success from a POST operation;

  • 204 No Content Success from a GET operation with empty data;

Errors:

  • 422 Unprocessable Entity Data you have sent to the server can’t be processed, or a validation error occurred;

  • 404 Not Found Resource can’t be found;

  • 403 Forbidden Request can’t be authorized;

  • 500 Internal Server Error server is experiencing an unknown error;

Troubleshooting:

  • 422 Unprocessable Entity assert request Content-type with data type sent e.g. if you try to send a JSON body with Content-type: application/xml server will interpret your JSON body as XML and won’t be able to process it;

  • 404 Not Found check resource identifier, also check if resource you requested was not deleted or not yet created;

  • 500 Internal Server Error check the integrity of data you send (verify closing tags of XML body and validity, verify JSON validity), if error persist please contact us.

Rate Limitations

Assembla Developer API allows you to execute not more than 240 requests per minute with burst of 20 requests per second.

When rate limit is exceeded, requests will be terminated with error code 429 (Too Many Requests).


For more information, check out our API Documentation Site.

If you have any questions or need our assistance, don't hesitate to contact us at support@assembla.com. 

Did this answer your question?