> For the complete documentation index, see [llms.txt](https://docs.cootje.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cootje.com/cootje-api/swagger.md).

# Swagger

De technische naslag van de Cootje API: waar je Swagger vindt, wat erin staat en hoe het verschilt van deze handleiding.

Swagger is de technische naslag van de Cootje API: één overzicht van alle aanroepen, met hun velden en antwoorden. Deze handleiding beschrijft de meest gebruikte aanroepen stap voor stap. In Swagger vind je ze allemaal.

* **Adres:** [mijn.cootje.com/api/swagger](https://mijn.cootje.com/api/swagger)
* **Token:** niet nodig om Swagger te bekijken

## Twee overzichten

Bovenaan de pagina kies je bij **Select a definition** welk overzicht je wilt zien:

| Keuze                   | Wat erin staat                                                                                        | Als bestand                                                 |
| ----------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| **Cootje API**          | De algemene aanroepen: inloggen, recruitment, personen, bedrijven, contracten, urenstaten en facturen | `https://mijn.cootje.com/api/swagger/v1/swagger.json`       |
| **Cootje Planning API** | De aanroepen van de planning                                                                          | `https://mijn.cootje.com/api/swagger/planning/swagger.json` |

## Wat je in Swagger ziet

* De aanroepen staan gegroepeerd per onderwerp. Klik een aanroep open voor de uitleg, de velden, een voorbeeld van het verzoek en de mogelijke antwoorden.
* Een slotje bij een aanroep betekent dat je er een token voor nodig hebt.
* Onderaan de pagina staan onder **Schemas** alle objecten met hun velden.

## Verschillen met deze handleiding

| Onderwerp               | In Swagger                                                                     | In deze handleiding                                                                              |
| ----------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| Schrijfwijze van paden  | Met hoofdletters, zoals `/recruiter/Vacancies`                                 | In kleine letters, zoals `/recruiter/vacancies`. De API maakt geen onderscheid, dus beide werken |
| Het begin van het adres | Paden staan er zonder het begin                                                | Elk pad komt achter `https://mijn.cootje.com/api`                                                |
| Taal                    | Engels                                                                         | Nederlands                                                                                       |
| Verplichte velden       | Niet aangegeven bij de velden zelf. Soms staat het in de uitleg van de aanroep | Op elke pagina staat wat verplicht en wat optioneel is                                           |

## De bestanden gebruiken in je eigen gereedschap

De twee bestanden volgen de OpenAPI-standaard, versie 3.0. Je kunt ze inlezen in gereedschap zoals Postman, of er code voor je eigen koppeling mee laten maken.

```bash
curl -o cootje-api.json "https://mijn.cootje.com/api/swagger/v1/swagger.json"
curl -o cootje-planning-api.json "https://mijn.cootje.com/api/swagger/planning/swagger.json"
```

In de bestanden staat geen adres van de API. Stel in je gereedschap daarom zelf `https://mijn.cootje.com/api` in als begin van elk adres.

## Aanroepen uitproberen

Swagger heeft de knoppen **Authorize**, **Try it out** en **Execute** om een aanroep vanuit de pagina te versturen.

{% hint style="warning" %}
Aanroepen versturen vanuit Swagger werkt op dit moment niet. Swagger stuurt de aanroep naar een adres zonder `/api`, en je krijgt dan de webpagina van Cootje terug in plaats van een antwoord van de API.
{% endhint %}

Gebruik Swagger om een aanroep op te zoeken en verstuur hem met je eigen gereedschap. Met `curl` ziet dat er zo uit:

```bash
curl "https://mijn.cootje.com/api/recruiter/vacancies" \
  -H "Authorization: Bearer JOUW_TOKEN"
```

Hoe je aan een token komt, staat op [Token Ophalen](https://docs.cootje.com/cootje-api/authenticatie/token-ophalen.md).
