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.01 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)
1 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.