endpoints

By PetHub, 23 January, 2023

/Foods

The /foods endpoint focuses on the types of pet food that is recognized by and can be recorded on PetHub.com for a pet's nutritional needs. Use this to pull the types of foods available and details about a specific food ID (fid).

Digging into /Foods

The /foods endpoint offers the following:

/foods	Description
/	POST - add a food to PetHub's list of foods, types, etc. GET - list of foods available on PetHub Example: https://pethub.io/v1/foods?manufacturer=mars&type=kibble
/{fid}	GET - retrieve manufacturer, brand, type, name, and so on PUT - update information about a food entry DELETE - remove a food entry from the database
/{fid}/use	GET - get the list of pets using food {fid} Example: https://pethub.io/v1/foods/{fid}/use?state=wa&city=seattle
	(Actively seeking feedback re: additional endpoints & use cases)

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

Category

By PetHub, 23 January, 2023

/Activities

The /activities endpoint provides a current list of supported activity types.

Digging into /Activities

The /activities endpoint offers the following:

/activities	Description
/	GET - returns a list of supported activity types
/{aid}	GET - returns detailed information about the activity identified by the activity ID PUT - updates an activity entry DELETE - deletes an activity entry

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

Category

By PetHub, 1 January, 2023

/Types

The /types endpoint focuses on the types of data that can be associated with a pet's profile on PetHub.com. Use this to retrieve the list of type names and unique IDs to associate with a pet's profile information.

This endpoint:

Category

By PetHub, 1 January, 2023

/Pets

The /pets endpoint focuses on the pet profile on PetHub.com. Use this to create a pet profile, retrieve a pet's information, and update its details as documented here.

The main parameter of this endpoint is the pet ID {pid} which is a UUID for a pet.

Digging into /Pets

The /pets endpoint offers the following:

/pets	Description
/	POST - creates a new pet profile
/{pid}	GET - returns basic profile information such as name, photo, breed, species, age, description, and so on PUT - updates a pet's basic profile information DELETE - deletes a pet's basic profile and causes all associated data to be deleted as well (e.g. activities, allergies, documents, conditions, foods, medications, etc.)
/{pid}/activities	POST - add an activity for a pet GET - return list of activities for a specific pet DELETE - remove an activity for the pet
/{pid}/allergies	POST - add an allergy entry for a pet GET - returns a list of allergies associated with a pet PUT - updates a pet's existing allergy information DELETE - deletes the pet's specified allergy entry
/{pid}/conditions	POST - add a condition entry for a pet GET - returns a list of conditions for the specified pet PUT - updates a pet's existing condition information DELETE - deletes the pet's specified condition entry
/{pid}/documents	POST - add a file to a pet's profile GET - list of documents associated with the pet DELETE - remove a document from the website and pet's profile
/{pid}/foods	POST - add a food entry for a pet's diet GET - retrieve a list of foods on a pet's diet PUT - update a pet's food regimen DELETE - remove the food entry from the pet's profile
/{pid}/medications	POST - Add a medication entry for a pet GET - retrieve a list of medications and their details for a pet PUT - update a medication entry for a pet DELETE - remove a medication from the pet's profile
/{pid}/procedures	POST - add a medical procedure entry for a pet GET - returns a list of medical procedures associated with this pet PUT - update the medical procedure entry DELETE - remove a procedure from the pet's profile
/{pid}/tags	POST - links a tag to the pet GET - returns a list of IDs linked to the pet's profile DELETE - unlink the tag from the pet's profile

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

Swagger 2.0 File

Category

By PetHub, 1 January, 2023

/Persons

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:

/persons	Description
/	POST - Creates a new user account GET - search for a person's basic account information using their email address or username. Examples: https://pethub.io/v1/persons?email=john@example.com https://pethub.io/v1/persons?username=johndoe
/{uuid}¹	GET - returns basic account information such as email address, unique username, creation date, last login PUT - updates an existing user's account DELETE - Removes the user account and any content provided by the user (requires elevated permissions)
/{uuid}/authorized	GET - list of API key IDs user has approved for accessing their account and data (requires elevated permissions)
/{uuid}/perks	POST - add a perk to a user's list of perks GET - list of perks claimed by the user (can filter by expiration and status) Example: https://pethub.io/v1/persons/3295c76acbf4caaed33c36b1b5fc2cb1/perks?status=active (returns only active perks and excludes those that have expired) DELETE - remove a perk from a user's list of claimed perks
/{uuid}/pets	GET - the pets type causes the API to return a basic list of the user's pets perfect for using in a list that allows drilling deeper into an individual pet's information Example: https://pethub.io/v1/persons/3295c76acbf4caaed33c36b1b5fc2cb1/pets?species=dog (returns list of user's pets that are dogs)
/{uuid}/policies	POST - add a policy to a user's profile GET - list of all insurance policies added to the site by the user and to which pets the policy applies DELETE - remove a policy from a user's account
/{uuid}/profile	GET - deeper information about the user's account information, including first name, last name, main telephone number(s), additional email addresses, and mailing address PUT - updates a user's profile
/{uuid}/safetyCircle	POST - add a safety circle contact (including to which pet(s) is/are known by the person GET - list of Safety Circle contacts the user has added to the website. Also includes a list of pets each of the contacts knows (optional query attribute pet_id may be used to filter by pet) PUT - update a contact's information (including which pet(s) are known by the contact) DELETE - remove an emergency contact from the user's list
/{uuid}/subscriptions	POST - add a new subscription to the user's account GET - which subscriptions have been purchased by the user, to which pet they apply, when they were purchased, and when they expire DELETE - terminate a user's subscription

¹ {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.

Swagger 2.0 File

Category

By PetHub, 1 January, 2023

Getting Started

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:

/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
/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
/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.

Category

endpoints