Register your Application

Before you start with the API, please register your application. We will send you access to a sandbox server to test your integration.

Play with the Interactive Documentation

We use Swagger to automatically document our API and provide you an interactive playground.

General API Client Guidelines

The Reverb API is a Hypermedia HATEOAS style API following the application/hal+json standard.

That means every action you can take in the API is documented from within the API. By following the root url, you can discover every capability in the API. Here are some guidelines to follow:

1. Clients should set their Accept header to application/hal+json.
2. Clients should never construct their own URLs or assume anything about the URL structure of the application.
3. Clients should follow links in the _links element of the response body, according to the application/hal+json media type.
4. Link hrefs will be relative to the base API url (https://reverb.com/api).
5. Links are sometimes verbs like "add_to_wishlist" and sometimes resource nouns like "lists". We are moving to mostly resource nouns for the next version of the API. Most links will respond to one or more of the HTTP verbs (GET/POST/PUT/DELETE). If any verbs are not supported, you will get a 405 Method not accepted response back.
6. Clients should use standard HTTP libraries that respect things like 304 Not Modified caching responses and ETags.
7. Requests are sensitive to the Content-Type header. If you use application/hal+json your body must be a json encoded string. If you use application/x-www-form-urlencoded, your body must be a urlencoded parameter string. Example:

Getting Started: Authentication

The examples below will use the curl command to show how to execute requests.

To get started, obtain an Auth Token by logging in or signing up. Attempting to access any resource other than the auth and account creation endpoints will result in a 401 Unauthorized code until you start sending the token. Learn more about authentication.

curl -H "Accept: application/hal+json" //reverb.com/api/wants

{"error":"Invalid token. Please re-authenticate to obtain X-Auth-Token header.",
"_links":
  {"authentication":
    {"templated":true,
     "href":"//reverb.com:80/api/auth/token{?email,password}",
     "method":"POST"}}}

curl -i -X POST --data "[email protected]&password=my_password" https://reverb.com/api/auth/tokens

{"token":"yic7l3453QyRgMua45Zz"}

curl -H "Accept: application/hal+json" -H "X-Auth-Token: yic7l3453QyRgMua45Zz" //reverb.com/api/wants

Pagination

All collection-based api calls will return _links that include next and prev keys. These hrefs should be followed. If they are not present, there is no next or previous page.

API Documentation

Besides the self-documenting nature of Hypermedia APIs, the API is documented using Swagger to provide a JSON version of the documentation. at //reverb.com/api/doc.json

To visually explore the API, you can use Swagger-UI. Just visit: Reverb Swagger API To access user-based parts of the api, make sure you put in your authentication token in the upper right hand textbox of Swagger. Once you put it in, hit Explore to refresh the page. From this point, any requests you make on the Swagger page will contain your token.

Response Codes & Error Handling

The API will use standard HTTP response codes where appropriate. Clients should respond appropriately to things like 304 Not Modified statuses.

In the case of missing parameters, a 412 code with a message key is shown, mapped to a text message.

For POST requests, the 412 error code will be returned for validation errors with a field by field breakdown. If the errors element is present, it will be a json hash of fields to messages. For example: