Introduction

Version 5 of the RescueGroups.org API is currently under development.  On 2/15/18, we released an alpha developer preview of RescueGroups.org API v5. This is a very early release involving only the Animals endpoint.

On 10/5/19 we released a major update to the v5 API.  Please see the notes below.

On 1/24/20 we released a minor update to the v5 API.  This update involved mostly changes to the backend.  Please see the notes below.

This API will change in the coming months.  We would greatly appreciate your feedback and ideas for improvement.  However, perform development at your own risk.  We would expect changes to be relatively minor, but there's no guarantee.

Changes and improvements of note

• Closely follows the JSON API specification.  v2 was a completely custom and non-standard request and response structure.
• Uses industry standard HTTP verbs/methods (GET, PUT, etc) and endpoint URLs.  v2 used one URL and everything was a POST.
• API Key is accepted only on Authorization header.  In v2 the API Key was taken from the URL.
• Multiple sort values using +/- are supported.  In v2 only one sort field was supported with asc/desc.
• Random sort now available.  In v2 random was not available.
• Distance filter is it's own properties in POST body and supports either miles or kilometers.  In v2 the radius filter was included with any other filters.
• Related objects can be included in the response body but separate (eg., Organization along with Animals).  In v2 related object fields were either mixed with the requested object or an additional request to the API was necessary.
• Some fields are considered meta and returned separately from the other properties (see the meta Option).  In v2 all fields were the same, even if they were meta.
• Endpoint URLs can include view names to automatically add filters.  In v2 filters could only be added in the POST body.

Improvements/changes made with the update on 10/5/19

• If an attribute or relationship doesn't exist (ie., is null), that element will no longer be returned in the result. This will result in smaller results transfer sizes and make it easier to read and understand result data.
• Compression (gzip) has been enabled on the API server.
• All entity meta properties are now returned as entity attributes. Meta is only provided at the top-level of the response data.
• The top-level meta data now includes more information about the request and results, including a transactionId that can be used when requesting assistance from RescueGroups.org.
• We're simplifying the API by removing endpoints that weren't being used.
• Endpoints are now grouped in the documentation so that all endpoints of the same type (eg., animals) are together.

Improvements/changes made with the update on 1/24/20

• Geolocation now accepts postalcode, coordinates, or lat and lon in order to calculate distance for animals and organizations. Refer to the Endpoint reference for more information about how to perform a distance query for animals or organizations.

Swagger definition available

Coming soon!  You can download an early draft of our Swagger definition for the public API endpoints.

To open the definition go to the Swagger Editor and click File > Import URL and paste the URL above, once it's available.

Postman collection available

We have a public Postman collection available to help you with examples.

Developer community

Please join our developer community in Google Groups: https://groups.google.com/a/rescuegroups.org/forum/#!forum/apidev

Common questions

Question: When will this version of the API be available in production?

We don't have any ETA for production release yet.  We are hoping that it will be in production by early-2020.

Question: Will the current APIs (v2 and the REST API) be deprecated?

Yes, we expect to discontinue use of the current APIs as some time after v5 goes live.  We will provide plenty of notice beforehand.  We expect to have multiple APIs running in production for a year or more.