API V1

The /Persons endpoint focuses on the user account on PetHub.com.

Use this to create a user account, retrieve a user's information, update their details, and retrieve a list of content they own (including pet profiles, documents, safety contacts, and so on). Then, if it is necessary to dive deeper into detail, use the other APIs to access specific details about those Types of content.

Security: this information is only available if the user has provided both access to the requesting application and permissions to access the type of information being requested. If a user provides access to their account but has not given permission to view Documents or Insurance information, for example, an error 400 (Bad Request) will be returned.

Digging into /Persons

The /persons endpoint:

¹ {uuid} is the universally unique identifier returned when a GET request is made to the /persons endpoint by an authorized API integrator

The Swagger 2.0 / OAS YAML rendering is below including the data structures necessary for POST or returned by GET.

PetHub APIs support a number of endpoints that, with your feedback, we will continue to add to our library. The APIs below are what are currently in our catalog.

We've broken these up into 3 sections:

• Sniffing Around - both the most commonly used API calls for starting an interaction with a user's account and also the calls you'll need when initially registering your application with PetHub and getting a user's permission to utilize their data
• Digging Deeper - endpoints that help you dig deeper into a user's or pet's information
• Webhooks - proactively pull information as well as register to have PetHub notify you when specific events have taken place (such as tags being scanned or lost pet alerts being sent, for example)

The fun stuff:

• Sniffing Around:
  • Authorizations - before a 3rd party application may interact with a PetHub user's account and data, it may first receive authorization from the PetHub user
  • Persons - the end-user with the account on PetHub who has control of their own and their pet's content
  • Pets - the profiles of the animals managed by the PetHub platform
• Digging Deeper:
  • Activities - walking, agility, eating, playing, training, sleeping, pooping, and more. This is how you list it and add to it for a particular pet
  • Foods - manufacturer, formula, type (wet? kibble? raw?), amount, timing, and special preparation instructions can be found or added to for a pet with this endpoint
  • LostPets - pull a list of lost pet posters for a user, specific pet, by geo location, and more. Or, add to our list of Lost Pet posters
  • Perks - view which discounts a PetHub subscriber has claimed or the entire list of Perks that could be claimed
  • Species - pull the list of species supported by the PetHub platform or look-up the species for a specific pet
  • Tags - ability to look-up tag information including a pet's profile information if publicly published by the pet owner
• Webhooks:
  • Alerts - announcements about missing or found animals
  • Notifications - tag scanning events (webhook) for a particular pet or particular tag ID

Each of these can be accessed with permission from the user whose data is being requested. In addition, the user can see which applications have been given permission to use their data which can be revoked at any time. Lastly, the user can control which of these types of resources each application is allowed to access on a read / write / update / delete basis.

In the case of our favorite original tester, Grizzly, requesting his information would take the following form:

curl -H "Authorization: Bearer abc123" GET https://pethub.io/v1/pets/223

The above authorized call to PetHub.io's "/v1/pets/{id}" endpoint with Grizzly's unique identifier (where "223" replaces the "{id}") would receive the following response:

{
    "pid": "223",
    "uid": "66",
    "name": "Grizzly",
    "species": {
      "tid": "3031"
    },
    "breed_primary": {
      "target_id": "2855"
    },
    "breed_mix": "Chihuahua",
    "gender": "Male",
    "picture": {
      "fid": "189",
      "uid": "66",
      "filename": "grizzly.jpg",
      "filemime": "image/jpeg",
      "filesize": "7735",
      "status": "1",
      "timestamp": "1414801248",
      "type": "image",
      "metadata": {
        "height": 280,
        "width": 186
      },
      "height": "280",
      "width": "186",
      "url": "https://images.pethub.com/dev/pub/grizzly.jpg?milgJeq.a.UHYX6vfvnF7f2alm0p1Y5H"
    },
    "birthday": "2013-11-16 00:00:00",
    "size": {
      "tid": "3236"
    },
    "weight_value": "4",
    "weight_unit": "lb",
    "coat": "Short Hair",
    "tail": {
      "tid": "3428"
    },
    "altered": {
      "value": "Yes"
    },
    "description": "Our precious fuzzi-wuzzums.",
    "microchip": ""
  }

The format of the data above is JSON which is the default format typically specified in the Header as part of the request. However, if necessary, the format can be explicitly requested by appending ".json" or ".xml" to the noun to receive JSON or XML formatted data, respectively. For example:

curl -H "Authorization: Bearer abc123" GET https://pethub.io/v1/pets.json/223

With a few exceptions, the PetHub API is generally accessed through HTTP request methods (e.g. GET, POST, PUT, DELETE) that follow a general pattern:

https://pethub.io/v1/{noun}
https://pethub.io/v1/{noun}/{id}
https://pethub.io/v1/{noun}/{id}/{type}

The "v1" is simply to help us provide versioning with our APIs. That way when we start working on a version 2 will can void disrupting any applications utilizing the previous version. The {noun} is the type of resource that is being worked with and the {id} is the identifier for a specific resource being acted upon. The {type} parameter allows for a scoped search in certain situations.

Part of authenticating each request is the use of the aforementioned access token that is passed as part of the header in the request. Using cURL as an example of what this might look like, the request would look similar to the following:

curl -H "Authorization: Bearer {access_token}" GET
https://pethub.io/v1/{noun}/{id}

See the documentation on Authentication for additional details about obtaining the value that would replace the {access_token} entry shown above. Also, for the sake of clarity, please note that the curly braces are a documentation preference and not literally included when substituting your actual values. For example, if your access token were "abc123" and the noun was "pets" and the individual pet's ID was 321, the statement using the above syntax would be:

curl -H "Authorization: Bearer abc123" GET
https://pethub.io/v1/pets/321

Further Explanation

Exploring the above example further, let's dissect this statement to better understand it:

• curl - this is the command-line tool for transferring data (cURL)
•  -H - the "-H" or "--header" option allows custom header settings to be passed to the server (in this case, we are adding in the "Authorization: Bearer abc123" string to the header as part of the request)
• GET - the HTTP method being used in this request to the server followed by the URL

If the endpoint supports parameters, those can be included as part of the URL.

PetHub uses OAuth for secure authentication.

To get started you need to:

1. Submit an API Key Request form
2. Create a PetHub.io account (invitation only - details provided when API key is assigned)
3. Send requests to our servers with proper authentication (e.g. you can use cURL for testing)

Once you have your API Key and Secret, combined those can be used to request an access token. It is this token that is passed with each API request sent to our servers.

To get an access token, simply make the following request (replacing {API-KEY} and {API-SECRET} with the information associated with your account):

curl -d "request_type=api_credentials&api_key={API-KEY}&api_secret={API-SECRET}"
https://pethub.io/v1/oauth2/token

The PetHub.io server will send back a response similar to the following:

{
    "token_type": "Bearer",
    "expires_in": 1800,
    "access_token": "some-alphanumeric-token"
}

Introduction

The PetHub API (Application Programming Interface) allows you to access the PetHub database of nearly 1-million pets¹. You can use the API to build your own mobile applications, dynamic websites and connectors where PetHub acts as your back-end database. Our goal is to be the pet owner's "single source of truth" for managing their pet's data and allowing them to share their pet's data outside of PetHub in a safe and secure manner with trusted applications and services.

With the PetHub API, the goal is to allow approved developers to create, read, update and delete information on the PetHub.com site with the user's permission. For more information about our overall approach for this version 1, see our article, "PetHub Open API v1.0 -- Approach."

Using the API

The PetHub API is a RESTful API, meaning that it uses published URLs to access resources and return meaningful HTTP response codes. This enables the use of POST, GET, PUT, DELETE methods/verbs and requires proper HTTP authentication. The API supports cross-origin resource sharing allowing for secure and safe use from a client-side web application. The API is used by sending requests with a specific data structure to PetHub's servers which require authenticated access tokens for all API requests.

We've also design the APIs using an API-first, abstracted layer approach. That means we're wanting to design the APIs as developers would want to use them, not as they would to be built based on the designs of our systems. As our systems change on the back-end, there should be minimal to no impact to your use of the APIs.

Not sure where to begin? Read our Getting Started page for a high-level idea of the organization of these pages and how to put them to use based on your level of expertise. We're eager to see what you create and we're here for your ideas on additional APIs to add to further enable your vision.

¹ This, of course, is only possible when a pet owner both provides that permission and continues to allow it (with the ability to modify permissions at any time including full denial of access or deletion of all data from PetHub itself).

It's always fun -- whether daunting or not -- when starting a new project especially with a variety of APIs and philosophies for creating RESTful web services. It's like going into a garage whose walls are lined with power tools and thinking, "Think of the cool things I could build!"

We've documented our approach for this PetHub version 1 in, "PetHub Open API v1.0 -- Approach." The purpose of this Getting Started page is to give you a high-level view of how we've organized the documentation, where to find samples to leverage in building your own PetHub-enabled apps & integrations, and community to offer further guidance to one another as we continue to improve this open API.

Organization

Our documentation is written in HTML5 and Swagger/OAS 2.0¹ and grouped into 5 sections:

• API Calls - an introduction to getting setup with making API calls to PetHub's web services
• Endpoints - index into all of the public APIs currently provided by PetHub
• Response Codes - list of HTTP response codes currently supported by the API
• Developer Resources - where to find more help in the form of sample code, forums, and general assistance
• Support - deeper help to report errors and open support tickets

We suggest you start with the API Calls section first to learn about how to create an authenticated connection, formatting requests to be sent to our APIs, and what to expect in the responses that you receive back. Once you feel comfortable with that information, you can dive right into the APIs and start playing.

The 3 starting APIs are:

1. /Authorizations - this is used to create that digital contract between you and a PetHub user wanting to utilize whatever solution you've created. Here is where you will send your request along with details about what data you'd like access to and your unique ID and details to help identify your app in the user's list of trusted integrations
2. /Persons - this endpoint is at the top of the hierarchy. The user account is referred to as a Person and owns all content they've added through their account on PetHub.com
3. /Pets - this is the next tier where the Pet, while associated with the Person, could own or share in ownership data

The /Persons and /Pets endpoints will most likely be your starting places when determining the unique IDs associated with the Person and Pet objects on PetHub.com. Once you know which Person or Pet your are working with, you can then dive down deeper into the data that makes sense for your application's use-case for helping our users edit, add to, and safely utilize their data through your PetHub-enabled solution.

Getting Around

While navigating this documentation, in addition to using the index on the side of the page, you will also find a list of links at the bottom under the Category heading. These links can help you view related content with API V1 being a category shared by all of the documentation (if you want to see it all in one big list, for example). We've also made it possible to download a page into a PDF file for later review if you anticipate being offline. On the pages showing details and Swagger 2.0 (OAS) visual representations of our APIs, you can download the YAML file to pull into whatever tools you use when developing with web services.

Resources

This is a work in progress as these are our debut open APIs and so we will be adding to this section of the Getting Started document as we are guided by questions from our software development community. Please take a moment and share any thoughts you have around what we could put here or elsewhere on this site to allow you now (or others who come after you) to more quickly understand and engage with what we're creating. (Drop us a note)

¹ We're using the OpenAPI Specification (fka: Swagger Specification) version 2.0 as we design and document our v1.0 because we've found this is the most supported version by some of the 3rd party tools we want to work with. If there are tools that use OAS 3.0 that you'd like to use with our documents, we've written our documentation simply enough to enable easy migration to the newer standard.