Fichaloto

Blog Integration

What to ask an HR API before you write a line of code

6 min read

Every vendor says they have an API. The interesting questions are what it covers, what it refuses to do, and whether it obeys the same rules as the screens.

Coverage: is it the whole product or the demo?

The first question is boring and decides everything: which entities can you read and write? Plenty of APIs cover customers and projects and stop exactly where the interesting data starts — schedules, shifts, absence balances, clocking records, permissions.

A good sign is an API whose entity list is generated from the same definition as the import and export screens, rather than maintained by hand. When they are separate lists, one of them is always out of date, and it is usually the one you are building against.

Writes: same door, same rules?

The failure that costs the most time is an API that writes straight to the database, skipping the validation the screens apply. You discover it months later, as a population of records that could not have been created through the interface and that half the product does not know how to display.

Ask directly: does creating a record through the API run the same validation, fire the same side effects and land in the same audit log as creating it on screen? If the answer is anything other than an immediate yes, budget for the cleanup.

What should be read-only, and why that is reassuring

A well-designed API refuses things. Records with evidential value — a chained clocking register, an issued invoice, a movement history — should be readable and not writable, because writing one by hand would forge exactly the thing that makes it worth keeping.

This is worth reframing when you are evaluating: an API that lets you POST anything is not more capable, it is less trustworthy. What you want instead is a documented front door for the legitimate case — bulk-loading history from your previous system, for instance, which should go through the same code path that generates the records properly rather than around it.

Keys, scope and the boring security questions

Three things to check, all of which are quick to verify and expensive to discover later.

  • Is the key scoped to an account? In a multi-tenant product every query must filter by tenant at the model layer, not at the controller. Ask what happens if you request an ID belonging to someone else: the honest answer is 404, not an empty array.
  • Does the key carry a role? A key should hold permissions the same way a person does, so a read-only integration is read-only by construction rather than by good intentions. Built-in read-only and read-write API roles save everyone from hand-ticking forty checkboxes and getting one wrong.
  • Is the secret shown once? If you can go back and read an existing key's secret in the interface, so can anybody else who gets into that screen.

Frequently asked questions

Do you have webhooks?

Fichaloto is polling-first today: entities expose a modified-since filter so an integration can pull only what changed. It is less elegant than webhooks and considerably easier to debug at three in the afternoon.

What format are timestamps in?

UTC, always, in the API. Dates that represent a working day are stored as the local calendar day separately, because a night shift otherwise splits across two days depending on the time of year.

All of this is built into Fichaloto. See how it works.

Keep reading