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:
Clients should set their Accept header to application/hal+json.
Clients should never construct their own URLs or assume
anything about the URL structure of the application.
Clients should follow links in the _links
element of the response body, according to the application/hal+json
Link hrefs will be relative to the base API url (https://reverb.com/api).
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.
Clients should use standard HTTP libraries that respect things like 304 Not Modified caching responses and ETags.
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.
Actions requiring user login will return 401 status codes. The client should present users with a login screen and store credentials locally. The authentication url is embedded as a link, using the same HAL standard as the rest of the API. Additionally it's using the URI Template to specify which parameters to send (email and password). Clients may optionally parse the URI template to ensure they're sending the right parameters.
The response to either request above will contain a token element. Use this element in all your subsequent requests by setting the X-Auth-Token header. For example:
curl -XGET -H "X-Auth-Token: tokenfromabove" https://reverb.com/listings
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.
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:
API Clients and Sample Code
The following libraries may be useful to you as you develop your integrations.
If you're working with our API, we encourage you to sign up for the Reverb API Forum where announcements about API changes are posted. You can also ask questions about API usage there for the quickest response.