API basics for beginners

What is an API, really?

API stands for Application Programming Interface. That sounds intimidating, so forget the words for a moment and picture a restaurant.

• You (the customer) want food, but you are not allowed into the kitchen.
• The waiter takes your order, brings it to the kitchen, and returns with your meal.
• The kitchen does the actual cooking, but you never see how.

An API is the waiter. It is the messenger that lets one system ask another system for something — without needing to know how the other system works inside.

In our world:

• You = another program (for example, a payroll system or an HR tool).
• The kitchen = Protime, where all the time and attendance data lives.
• The waiter (API) = the Protime API, which carries requests back and forth.

So when someone says “connect your system to Protime through the API,” they simply mean: “let your software ask Protime questions and receive answers, automatically.”

Why do APIs exist?

Without an API, getting data out of Protime means a person logging in, clicking around, exporting a file, and emailing it. That is slow, manual, and easy to get wrong.

With an API, another system can ask for exactly what it needs, the moment it needs it — for example, “give me yesterday’s clockings for everyone in the warehouse” — and get a clean, structured answer in a fraction of a second. No human clicking required.

A conversation: request and response

Every API interaction is a short conversation made of two parts.

1. A request — your system asks a question.
2. A response — Protime sends back the answer.

Think of it like sending a very precise text message and getting a reply.

   Your system  ──── "Can I have the clockings for July 1st?" ───▶  Protime API
   Your system  ◀─── "Sure, here they are: [list of clockings]"  ───  Protime API

That is the whole idea. Everything else is just detail about how the question is phrased and how the answer is formatted.

The five words you’ll hear most

You don’t need to memorise these, but recognising them makes every API conversation easier to follow.

What an answer looks like: JSON

When Protime replies, it doesn’t send a paragraph of text or a spreadsheet. It sends data in a format called JSON (pronounced “jay-son”). JSON is just a structured way of writing down facts so that both humans and computers can read it.

Here is a single clocking, written in JSON:

{
  "id": 18601,
  "date": "2026-07-01",
  "timeOfDayInMinutes": 510,
  "kind": "InOut",
  "person": {
    "id": 1
  }
}

You can read this almost like a form:

• id → a unique number for this clocking: 18601
• date → the day it happened: 1 July 2026
• timeOfDayInMinutes → 510 minutes after midnight, which is 08:30
• kind → the type of clocking: InOut
• person → who it belongs to: the person with id 1

The curly braces { } simply group facts together that belong to the same thing. That’s all JSON is: labels and values, neatly grouped.

“Read” versus “write”: asking versus changing

There are a few kinds of requests, but for understanding, only two matter:

Why do I need a “token”?

Protime data is sensitive — it’s people’s working hours. So the API will not answer just anyone. Before asking questions, your system first proves who it is and receives a token: a temporary digital pass.

The flow is two simple steps:

1. Show your credentials (a system’s username and password) → Protime gives you a token, valid for 30 minutes.
2. Attach that token to every question → Protime trusts the question and answers.

It’s exactly like a conference: you show your ID once at registration, get a badge, and then the badge gets you into every session for the rest of the day.

Putting it all together: one real example

Let’s follow a complete, realistic request from start to finish. Imagine an HR system wants yesterday’s clockings for one employee.

Step 1 — Get a token (prove who you are):

HR system → Protime: "Here are my credentials, may I have a token?"
Protime   → HR system: "Yes. Here's your pass, good for 30 minutes."

Step 2 — Ask the question (with the token attached):

In plain words, this address says: “Give me the clockings for person 1, on 1 July 2026.” The part after the ? is just a filter — the way you narrow down exactly what you want, like saying “only the warehouse team” or “only last week.”

Step 3 — Receive the answer (in JSON):

{
  "value": [
    { "id": 18601, "date": "2026-07-01", "timeOfDayInMinutes": 510,  "kind": "InOut", "person": { "id": 1 } },
    { "id": 18602, "date": "2026-07-01", "timeOfDayInMinutes": 1020, "kind": "InOut", "person": { "id": 1 } }
  ],
  "nextLink": null
}

Reading the answer:

• value holds the list of results — here, two clockings.
• The first is a clock-in at 510 minutes → 08:30.
• The second is a clock-out at 1020 minutes → 17:00.
• nextLink is null, meaning “that’s everything, there are no more pages.”

And that’s a full API interaction. Ask politely (with a token), be specific (with a filter), and receive a tidy answer (in JSON).

Common myths, cleared up

Where to go next

Now that the vocabulary makes sense, you can explore with confidence:

Further reading

• Your First API Call — see every step in action
• OAuth2 scope model — what a token is allowed to do
• Fetch resources — asking for exactly the data you need