Skip to content
Shepherd Developers

Sheppy gets an upgrade, and so do the docs

← Back to blog

·Shepherd Engineering ·3 min read

  • announcement
  • api
  • docs

Hey everyone, thanks for stopping by the developer portal.

You’ll notice something different on the way in: Sheppy has had a makeover. Our Brand Team put together a brand new portrait, headset on, bandana and all, and he’s now looking after the developer home page, and I believe you’ll find his icon in some of your support chats as well.

Sheppy isn’t the only thing that got an upgrade. We’ve just finished a full accuracy pass over the API reference. We try to do this in step with our regular releases, but don’t always get the chance.

What we did

We took every page in the API reference and checked it against the live schema rather than against our own memory of how the API works. Every endpoint path, every HTTP verb, field name in every request body, field in every schema table, and field in every example response.

That covered 286 endpoint references, 39 verb assertions, 37 request bodies, and 15 schema tables. We had a few areas where we needed to make corrections, and we made clarifications as well based on developer feedback to the team.

Example

Updating a record is a full replacement. Clients, patients, and appointments each have a PUT .../{id}/update endpoint. These are true PUT operations, which means any editable field you leave out of the body is treated as an intentional change and gets cleared. It is not a partial update, and there is no PATCH.

This will be most impactful on nested collections. Send a client update whose co-owner block has no phone array, and you have just told us that co-owner has no phone numbers.

The safe pattern is read, merge, write: fetch the current record with every nested collection embedded, apply your change in memory, then send the complete object back. There’s a full walkthrough in Updating records, and worked examples on Clients and Patients.

What else changed

  • Error bodies are JSON, in two different shapes. We used to tell you the body was plain text and that parsing it would throw. Errors now documents both shapes and how to write a reader that handles either.
  • Lookups are per-resource, not one endpoint. Breeds, sexes, statuses, units, and the rest each have their own endpoint. The Lookups page has been rewritten around the real ones.
  • Lookup IDs differ between sandbox and production. An ID from one environment will not validate against the other. This is the single most common cause of a rejected write, so it’s now called out wherever it matters.
  • Patient writes take lookup IDs, not free text. There is no species field on a patient; species is a property of the breed, so picking a breedId determines it. Required on create is name, clientId, breedId, sexId, statusId, and dateOfBirth. Patients has the full list plus a troubleshooting checklist for rejected writes.
  • Invoices, products, and SOAP records are read only. Better documented.
  • Corrected examples on appointment creation, client creation, and the patient file-upload flow, all of which had field names that would not have worked as written.

Swagger stays the source of truth

One habit worth keeping: when you need the exact shape of a request or response, check the live Swagger UI. It’s generated from the running API, so it can’t drift the way hand-written docs can. This portal exists to give you the concepts, the conventions, and working code around those schemas, not to be a second copy of them.

That’s also how this accuracy pass worked, and it’s how we’ll keep the reference honest going forward.

Thanks for building with us, and please don’t hesitate to reach out!