Home › API Documentation

UGAL API

The UGAL API is an interface to some of the features provided by the UGAL web interface.

We designed the API to comply with the principles of REST as much as possible:

• Every resource has its own URL.
• Resources are manipulated using standard http methods (GET, POST, PUT and DELETE).
• The outcome of a request is identified by the http status code of the response.

The API has 2 entry points:

• The website API, available to all websites and located at http://sitename.ugal.com/api/v1
• The partner API, reserved for UGAL partners and located at http://www.ugal.com/api/v1

Formats

The API understands and speaks both XML and JSON. XML is the default format. Append .json to your requests to receive responses in the JSON format.

• http://sitename.ugal.com/api/v1/orders/130904.xml
• http://sitename.ugal.com/api/v1/orders/130904.json

Depending on the format of the response, the response content-type is set to either application/xml or application/json.

Authentication

The API uses HTTP basic authentication to authenticate requests.

• Partner API requests should authenticate with the partner username and password set by UGAL at the time the partner account was setup.
• Website API requests should use "website" for the username and their API token for the password. The API token is available from the "My Account" tab of the website.
• Some parts of the website API are public (e.g. GET product list) and do not require authentication.

Example request:

curl -u website:60zb41ivby46 http://sitename.ugal.com/api/v1/orders/130904.xml

Your API token gives access to a lot of information about your website. Make sure to keep it secret and to share it only with trusted applications. In case of doubt, the API token can be revoked and a new one issued from the "My Account" tab of your website.

Reading collections and elements

Send GET requests to the resource URL to read through the API. For example:

• http://sitename.ugal.com/api/v1/orders.xml returns a collection of orders.
• http://sitename.ugal.com/api/v1/orders/130904.xml returns a representation of order #130904.

Filtering collections

Filtering a collection is done by appending query parameters to the request:

• http://sitename.ugal.com/api/v1/orders.xml?status=new returns a collection of new orders.

The list of query parameters that can be used for filtering is detailed for each application.

Pagination

By default a maximum of 25 elements are returned per request. Use the p query parameter to access the next elements in the collection:

• http://sitename.ugal.com/api/v1/orders.xml?p=2 returns the second page of orders.

Creating elements

Send a POST request to a collection URL to create a new element in the collection. The body of the request should contain a representation (XML or JSON) of the element. When the element is successfully created, a 201 status code is returned, the Location header is populated with the new element URL and the response body contains a full representation of the new element.

Updating elements

Send a PUT request to an element URL to update the corresponding element. The body of the request should contain the values to update (XML or JSON). Upon a successful update, a 200 status code is returned and the response body contains a full representation of the updated element.

Deleting elements

Send a DELETE request to an element URL to delete it. Upon a successful delete, a 204 status code is returned with an empty response body.

Error management

The outcome of a request is always indicated by the http status code of the response:

• 2xx status codes indicate success.
• 4xx status codes indicate client errors. Those are errors that you can fix by modifying your request.
• 5xx status codes indicate server errors. Those errors can only be fixed by UGAL.

Whenever possible additional information about the error is provided in the body of the response:

// Status: 400 Bad Request
<errors>
    <error>400.906 - User name must be provided</error>
    <error>400.908 - User email must be a valid email address</error>
</errors>

The list of error codes is available as an appendix.

Changes and Versioning

The current API version is v1, as indicated in the resources URL. New API functionalities and/or new elements to the XML and JSON responses will be added without a change of API version. Changes in the current data structure would however dictate a bump in the API version to keep your application backwards compatible.

Documentation conventions

• sitename is used in the documentation as a sample website name. Replace it by the name of the UGAL website you are working on.
• {variable} indicates a variable that should be replaced by your data.
• {...} indicates that a representation has been truncated. Refer to the description of the element itself for its full representation.