Sign up

Introduction

Welcome to the Greendizer API.

Greendizer is a RESTful webservice. It exposes a set of resources that a user can grant your application access to.

Audience

What you're about to read is designed for people familiar with HTTP, XML and JSON.

We have tried to make things easy by being as compliant as possible with all the standards that make the web such a great platform.

We would be glad to hear your comments and suggestions about it. Please send them to developers+at+greendizer.com.

General

Context

What your application is allowed or forbidden to do is defined by two parameters:

  • The API you are using: the Buyers or the Sellers API.
  • The rights granted to you by the administrator of your company, or the user on behalf of whom you're making the request.

Resources

If you're familiar with OOP, consider a resource as an object with a unique ID. Resources are organized in a virtual path. Each one has a unique URI, which is basically a permanent URL to it.

Greendizer exposes many resources:

  • User
  • Email
  • Invoice
  • Thread
  • Message

Collections

A collection is just a list of resources of the same type.

Collections include:

  • Emails
  • Invoices
  • Threads
  • Messages

ETags

An ETag is a unique value that changes every time a resource does. Here's how it looks like in Greendizer:

ETag: 1275417757277-512365

The left part is a timestamp representing the last time the resource has been modified. The right one is the ID of the resource.

When you make a request for a resource, the ETag header is sent back with the resource.

When you request a collection, expect also an ETag header for the collection, and an etag field in the representation of each resources it contains.

Used in conjunction with the right HTTP headers, ETags can greatly improve the performance of your application, and save you valuable bandwidth. See conditional retrievals

ETags are also very important to avoid conflicts when you try to update a resource. See conditional updates

Dates and times

Depending on the context, you will have to use ISO 8601 formatted strings, RFC 1123 or Unix EPOCH-like timestamps with millisecond precision:

Authentication

OAuth

oauth OAuth 2.0 is the authentication method we privilege. The standard is still a draft, but we think it's simple, easy and secure.

HTTP basic access authentication

This method is designed to allow you to provide credentials inside every request you make to the server.

Concatenate your email and password as following:
email:password
Then encode the result as a base64 string and add it to the headers of every request you make:
Authorization: Basic {base64 encoded string}

Important note

If you are a third party developer, OAuth should be the only method you implement as we strongly advise our users not to share their passwords with anyone. While easier, the HTTP basic access authentication method will most often look suspicious to them.

References

A buyer is the customer of sellers. He receives invoices and sends/receives messages.

A seller has customers called the buyers in Greendizer. He sends invoices, tracks them, and sends/receives messages.

You can find detailed information about the resources and collections exposed for each one of them by following one these links:

» Buyers reference

» Sellers reference

Requests

Root

All URIs are relative to the root of our API:

https://api.greendizer.com/

You can only access it over SSL.

Currently authenticated user

Use me with any end point to refer to the currently authenticated user.

For example, to access the current user's emails, use the following endpoint:

/buyers/me/emails/

Methods

GET Retrieves a resource or a collection of resources.
POST Creates a new resource
PATCH Partially modifies an existing resource. Please read the important note below
PUT Replaces an existing resource with a newer version
DELETE Deletes a resource
HEAD This method behaves exactly like a GET request but always returns a response with an empty body.
OPTIONS Lists the supported HTTP methods for a resource or collection.

Some browsers and firewalls can create difficulties when forming requests with specific methods. We provide an alternative solution: use POST and add a header named X-HTTP-Method-Override. The service will act upon it regardless of the actual HTTP method used:

X-HTTP-Method-Override: DELETE

Important: Unfortunately, the Patch method is not widely supported. To avoid problems with firewalls and proxies, we only allow it to be used when declared inside an X-HTTP-Method-Override header as explained above.

Output format

You must include an Accept header in the request to specify the output format of the response to be returned.

Supported formats and their corresponding MIME media types are:

JSON application/json or text/javascript or */*
XML application/xml or text/xml

For example, the following Accept header value will return JSON:

Accept: application/json

If a comma-separated list of MIME media types is provided, the server will skim through it (LTR) and select the first supported value it finds.

Paging

You may use the Range header as in the following example to ask the server to return parts of a collection and therefore use it for paging.

Range: resources={first}-{last}
first Zero-based index of the first resource to retrieve.
last Zero-based index of the last resource to return.

Including data

POST, PATCH, and PUT requests must include a Content-Type header to specify the format of the data they carry to the server.

Supported MIME media types are:

application/x-www-form-urlencoded Url encoded data.
application/xml XML, currently only used to send invoices.

A query string should look like this:

firstname=John&lastname=Doe&gender=Male

Conditional retrievals

Include the If-Match header in order to force the server to process your request only if the ETag of the resource or the collection you have requested matches the one you have.

If-Match: 1275417757277-512365

The If-Modified-Since header to force the server to see if the resource/collection has changed since a specific date before its sends it back to you.

If-Modified-Since: Wed, 02 Jun 2010 13:10:00 GMT

The If-None-Match header takes a list of ETags representing resources that are already available in your local cache and should therefore not be sent back again.

If-None-Match: 1275417757277-512365;127547854399-282365

Use the If-Range header in conjunction with the Range header to force the server to only retrieve the requested part of the collection if its ETag corresponds to the one you have specified. Otherwise, it will send you the first part of the new version of the collection to help you rebuild the representation.

If-Range: 1275417757277-512365
Range: resources=0-1

All responses come with an ETag and a Last-Modified header containing values you can use with the conditional request headers exposed above.

For example, the ETag of an invoice you have retrieved 5 minutes ago can serve as a value for the If-Match header of the request you are about to make to refresh it. This way, the server will only send you the invoice again if it has changed since your last request.


These headers are truly what makes the web magical. They can dramatically improve the speed and the performance of your applications.

Conditional updates

The If-Unmodified-Since and/or the If-Match headers should be used with PATCH and PUT requests to avoid conflicts when updating resources. If included, the server verifies that the resource hasn't been modified before applying the modifications.

If-Unmodified-Since: Wed, 02 Jun 2010 13:10:00 GMT
If-Match: 1275417757277-512365

Filters

Overview

You can filter the elements of a collection using a query string variable named "q" as following:

/buyers/1/invoices/?q=filter

A filter is a URL encoded string of concatenated [attribute][operator][value] groups separated by a "|" (pipe or vertical bar).

Attributes

Attributes are specific to the resource type you're handling.

Operators

<= Less than or equal to
<< Less than
>> Greater than
>= Greater than or equal to
== Equals

Values

Dates and times must be converted to Epoch-style timestamps with milliseconds precision.

For booleans, use 1/0 or true/false.

Examples

These examples show unencoded filter strings that you could use to filter invoices.


Return flagged and unread invoices only:

flagged==1|read==0

Return invoices with total exceeding $150,00:

currency==USD|total>>150

Responses

Format

When a reponse carries data, the format of its content depends on the value you have specified in the Accept header of your request.


Here's what you should expect if your request was aimed at a resource:

HTTP/1.1 200 OK
Date: Fri, 04 Jun 2010 15:35:00 GMT
Content-Type: application/json
ETag: 1275483600000-587452
Last-Modified: Wed, 02 Jun 2010 13:10:00 GMT
Server: spizer

{
    "createdDate":1275483600000,
    "firstname":"James",
    "lastname":"Hetfield"
}
HTTP/1.1 200 OK
Date: Fri, 04 Jun 2010 15:35:00 GMT
Content-Type: application/xml
ETag: 1275483600000-587452
Last-Modified: Wed, 02 Jun 2010 13:10:00 GMT
Server: spizer

<?xml version="1.0" encoding="UTF-8"?>
<user>
    <createdDate>2010-06-02</createdDate>
    <firstname>James</firstname>
    <lastname>Hetfield</lastname>
</user>

Here's what a request of a collection including a Range header would return:

HTTP/1.1 206 PARTIAL CONTENT
Date: Fri, 04 Jun 2010 15:35:00 GMT
Content-Type: application/json
ETag: 1275485740000-3691458
Last-Modified: Wed, 02 Jun 2010 13:10:00 GMT
Content-Range: users 0-1/2
Server: spizer

[
    {
        "createdDate":1275485740000,
        "uri":"https://api.greendizer.com/example/3691458/",
        "etag":"1275485740000-3691458",
        "firstname":"Jimi",
        "lastname":"Hendrix"
    },
    {
        "createdDate":1275485740000",
        "uri":"https://api.greendizer.com/example/78425142/",
        "etag":"1275483600000-78425142",
        "firstname":"Ella",
        "lastname":"Fitzgerald"
    }
]
HTTP/1.1 206 PARTIAL CONTENT
Date: Fri, 04 Jun 2010 15:35:00 GMT
Content-Type: application/xml
ETag: 1275485740000-3691458
Last-Modified: Wed, 02 Jun 2010 13:10:00 GMT
Content-Range: users 0-1/2
Server: spizer

<?xml version="1.0" encoding="UTF-8"?>
<users>
    <user>
        <createdDate>2010-10-01T20:42:37</createdDate>
        <uri>https://api.greendizer.com/example/3691458/</uri>
        <etag>1275417757277-3691458</etag>
        <firstname>Jimi</firstname>
        <lastname>Hendrix</lastname>
    </user>
    <user>
        <created>2010-10-01T20:42:37</createdDate>
        <uri>https://api.greendizer.com/example/78425142/</uri>
        <etag>1275417757277-78425142</etag>
        <firstname>Ella</firstname>
        <lastname>Fitzgerald</lastname>
    </user>
</users>

GET

200 OK The response contains the entire resource or collection in its body.
204 No Content No data was returned because the requested resource or collection is empty.
206 Partial Content The returned response contains only a part of the collection. This status code should only be expected if the request included a valid Range header.
304 Not Modified The resource or the collection has not been modified. This status code should only be expected if the request was conditional.

Responses with a 206 Partial Content status code are returned with a Content-Range header which contains information about the part of the collection you have received. The format is the following:

Content-Range: {unit} {first}-{last}/{total}
unit Represents the type of resources contained in the response.
first Represents the zero-based index of the first resource retrieved.
last Represents the zero-based index of the last resource retrieved.
total Represents the total number of resources available in the server.

All resources are serialized with a createdDate field that represents the date on which the resource was created on Greendizer.

POST

201 Created The resource has successfully been created and included in the body of the response along with its URI in the Location header.
202 Accepted The request has been accepted and queued.

PATCH

204 No Content The resource has been successfully patched. The body of the response is empty, and the ETag header contains an updated value.

PUT

200 OK The resource has been successfully updated and returned in the body of the response.
204 No Content The resource has been successfully updated and the body of the response is empty.

DELETE

204 No Content The resource has been deleted and the body of the response is empty.

Errors

Status Codes

Here's the exhaustive list of status codes that might be returned to you if your request failed:

400 Bad Request The request contained bad syntax.
401 Unauthorized Authentication is required. learn more about authenticating with OAuth on Greendizer.
403 Forbidden The authenticated user is not allowed or didn't grant your app enough rights to read or write the protected resource or collection.
404 Not Found The requested resource could not be found.
405 Method Not Allowed The request has been sent using an invalid or forbidden HTTP method. Allowed methods for that resource or collection are listed in the Allow header of the response.
406 Not Acceptable None of the MIME media types listed in the Accept header of the request is valid. Read the output format section to see the list of supported formats.
409 Conflict The resource could not be modified because one or many of the conditions in your request could not be matched. A copy of the latest version is included in the request.
413 Request Entity Too Large The requested collection is too large to be entirely returned. More about Paging.
416 Request Range Not Satisfiable The values in the Range header point to a part of a collection that's not available.
422 Unprocessable Entity The patch you are trying to apply to the resource is not valid. Equivalent to a 400 Bad Request status code for non-Patch requests.
500 Internal Server Error An unhandled error occured. Please let us know about it.
503 Service Unavailable The service is temporarly unavailable.

Description

You'll find a useful description of the error that caused your request to fail in the body of the response returned to you:

{
    "desc":"Error description comes here."
}
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <desc>Error description comes here.</desc>
</error>