PetHub Open API v1.0 - Approach

By PetHub, 1 January, 2023

PetHub Open API v1.0 - the struggle is always putting out a good first version of.. well.. anything. It's no different for putting out a solid API and so we did a lot of reading, learned from other developers over the years about what worked and what didn't, and landed on a solid approach that will, of course, change for the better. Until then, we have our v1 and we look forward to -- with your help -- creating an even better v2. It only works if you provide us with your thoughtful, critical feedback. For that, in advance, we thank you.

Tom Arnold
Founder, CTO
PetHub, Inc.

Purpose

PetHub has created a data repository for pet owners to safely enter and store their pets’ data. The goal of PetHub is to be that one repository that the pet owner can return to throughout the arc of their animal’s life when updating information, finding products and services, learning about how to give their pet a fulfilling life at each stage of their life, and to safely share their data with trusted PetHub vendors. To become and remain that once source of truth about a pet owner’s pet’s data, we must embrace that it takes a community to raise a happy, healthy, exceptional animal, and that requires that we make it easy for our users, vendors and partners to all connect for easy and safe sharing of data.

To accomplish this, PetHub is creating a version 1 open API. This idea was the goal of PetHub even before the company was formed and named. It’s an obvious need to create a platform and to have it survive only by enabling others to help you help them. This opinion was taken from how Microsoft Windows found adoption of its Microsoft Windows product in 1990 by creating an API to not only enable their development of applications for their operating system, but to allow others to use that same API when creating third-party solutions for that environment.

Design Methodology

In creating the version 1 of these APIs, we are taking a pragmatic approach as described in the ebook, “Web API Design: Crafting Interfaces that Developers Love,” by Brian Mulloy.

At a high level, this means we’re following these approaches:

  • Two base URLs per Resource - for example, /pets and /pets/321 – the first is for the collection and the second is for a specific element of the collection
  • Plural Nouns not Verbs for Resources - resources are named to best describe the resource while keeping verbs out of the name. We can rely on the HTTP verbs instead (e.g. Post, Get, Put, Delete)
  • Use Verbs for Non-resources - in the event of an action that is not acting on a resource, use a verb instead of a noun (e.g. /search )
  • Attributes and States - parameters are managed through the query string, ‘?’ and ‘&’
  • Error Messages - align to HTTP status codes (a small subset to keep it simple) and include the error status code, a granular error message, verbose description and link to the documentation (see Appendix A). In short: “Code for Code” and “Messages for People”
    • response_code - HTTP status code
    • message - verbose, plain language description of the the problem with hints of how to fix it
    • more_info - link to any supporting documentation
    • code - API error code to help further identify the issue
  • Versioning - the version number will be included in the URL, not the header, to make it easier to experiment with our APIs via a browser
  • Partial Responses:
    • “fields” parameter - partial responses may not be fully supported in v1 (still under consideration) but, in the case of the fields parameter, supporting it would allow a developer to request only specific fields in the returned data. Either way, the fields parameter should remain a reserved word in our development
    • Use limit and offset parameters - where in a list, offset is that starting element in the list and limit is the maximum number to be returned from that starting point (defaults: offset=0&limit=10)
  • Default Return Format - our default return format is JSON. We will support other formats if easily done (e.g. XML is a close second)
  • Naming Attributes - medial capitalization (i.e. “camelCase”) will be followed in general naming conventions for returned data. Uppercase / lowercase based on type of object
  • Support suppress_response_codes parameter - it set to true, HTTP status code 200 is always returned to help developers work with clients that do not allow developers to intercept errors
  • Authentication - OAuth 2.0 is the preferred method of authentication
  • Shortcuts - for common, grouped/composite data that needs to be returned, create shortcut APIs to avoid too many requests back and forth. For example, getting a pet’s public info would return the pet’s visible profile, emergency contacts, owner’s contact info, medical details, and so on, as marked by the pet owner as visible
  • API Facade Pattern - to abstract our third-party developer APIs, we will use a facade layer to better maintain a consistent API regardless of change happening to the system beneath. This also allows data stubs to be used when developing new APIs as well as provide a more seamless integration between systems

Customers

We begin by identifying and defining who will be using our APIs, whether they are our pet owners using them by way of a vendor’s third-party mobile application, the third-party app developer, and a closer integration with a trusted PetHub partner.

Appendix A - Supported HTTP Error Codes

While we could go with only 3 error codes to communicate “everything worked,” or “client error,” or “server error,” we’re going to support the following:

  • 200 - OK
  • 201 - Created
  • 400 - Bad request
  • 404 - Not found
  • 500 - Internal server error

We can add more as needed, but these should at least get us started with our version 1.

(See also: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes )

Tags

Comments