Openbare API's

Standaard antwoordt het GraphQL-endpoint van een app alleen aan wie zich identificeert: een sessie (van de schermen van de app of van wie bouwt) of een API-sleutel. Maar er zijn legitieme gevallen van anonieme toegang — een contactformulier op de website, een openbaar scherm om een status op te vragen, een open catalogus. Daarvoor bestaan de openbare API's: bewerkingen die u openstelt voor verzoeken zonder sessie en zonder sleutel.

De schakelaar is altijd van u, API voor API — en, bij de Tabel-API's, bewerking voor bewerking. Er wordt niets per ongeluk openbaar.

#Wat een anoniem verzoek is

Een verzoek aan het endpoint van de app (/api/graphql/gestao-clientes, of /api/graphql op het gepubliceerde adres) zonder sessiecookie en zonder de header x-api-key. Dat is wat de openbare schermen van de app doen — pagina's die vóór het aanmelden geserveerd worden — en elke externe client die u zonder inloggegevens aanroept.

#Een pipeline-API openbaar maken

1. Open de API in de builder.
2. Zet in de kop de schakelaar Openbaar (zonder sessie) aan — de tip bevestigt: "Toegankelijk zonder sessie of API-sleutel — voor openbare schermen van de app."
3. Opslaan. De API moet ook Gepubliceerd zijn — een concept wordt nooit aan anoniemen geserveerd, openbaar of niet.

#Bewerkingen van een Tabel-API openbaar maken

In een Tabel-API is de openbare toegang fijnmaziger: per actie. In het blok Tabel heeft de regel Openbare toegang (zonder sessie) één schakelaar per actie (Select, Insert, Update, Delete):

1. Schakel eerst de actie in bij Beschikbaar gestelde acties — alleen beschikbaar gestelde acties kunnen openbaar zijn; een actie uitschakelen schakelt ook de openbare toegang ervan uit.
2. Zet de openbare schakelaar alleen aan bij de bewerkingen die de openbare schermen nodig hebben. "Schakel alleen in wat nodig is" — dat is de regel van het huis.
3. Opslaan.

Een openbaar formulier om interesse te registreren heeft bijvoorbeeld een openbare Insert nodig — en niets meer: de lijst, het bewerken en het verwijderen blijven achter de sessie.

#Wat de anoniemen zien — en wat niet

Het endpoint behandelt de anonieme verzoeken met een eigen, strakker schema:

• Alleen de openbare API's bestaan. De overige verschijnen zelfs niet bij introspectie — ook de namen niet. Een anonieme partij kan niet opsommen wat de app aan privé-zaken heeft.
• Elke bewerking valideert de toegang. Een niet-openbare bewerking aanroepen in een anoniem verzoek geeft de fout "Operation not available without a session" — ook al kent men de naam.
• Concepten nooit. Alleen gepubliceerde API's.
• Er is een plafond aan verzoeken: 120 verzoeken per minuut, per app en per afzenderadres. Voorbij het plafond is het antwoord 429 met de header retry-after die zegt hoe lang u moet wachten. Ruim genoeg voor openbare schermen; het remt eenvoudig misbruik af.

#Aanroepen zonder sessie en zonder sleutel

Een anoniem verzoek is een gewone POST, zonder authenticatieheaders:

curl -X POST 'https://uw-host/api/graphql/gestao-clientes' \
  -H 'content-type: application/json' \
  -d '{"query":"mutation ($nome: String!, $email: String!) { registarInteresse(nome: $nome, email: $email) }","variables":{"nome":"Anna de Vries","email":"anna@voorbeeld.nl"}}'

Het tabblad Docs van de API geeft u het exacte voorbeeld — negeer daar de regel met x-api-key, die alleen geldt voor clients met een sleutel.

#Goede gewoonten

Gewoonte	Waarom
Stel zo min mogelijk bewerkingen open	Elke openbare bewerking is oppervlak dat aan de wereld blootstaat.
Geef bij de tabellen de voorkeur aan leesacties — en aan geteld gehouden velden	De boom Opgenomen velden geldt ook voor anoniemen: wat niet opgenomen is, komt er niet uit.
Openbare schrijfacties met verplichte argumenten en validatie in de pipeline	Een openbare Insert aanvaardt wat men hem stuurt — valideer in de stap Script of met regels van het model.
Bewaak in Radar	De openbare uitvoeringen worden met de toegangsmodus geregistreerd; afwijkende pieken ziet u daar.

#Waarom niet…?

• Ik heb de schakelaar aangezet en het anonieme verzoek blijft falen. Kijk naar de status: de API moet Gepubliceerd zijn naast Openbaar — en, bij een tabel, moet de juiste actie de openbare schakelaar aan hebben staan.
• Waarom geeft de browser een fout wanneer ik het endpoint open? De interactieve omgeving (GraphiQL) van het endpoint vraagt om een sessie op het platform — het is een gereedschap voor wie bouwt. De gegevens vraagt u op met een POST, zoals in het voorbeeld hierboven.
• Waarom krijg ik 429? U hebt het anonieme plafond van het adres bereikt. Wacht de tijd van retry-after af. Heeft uw integratie meer nodig, gebruik dan een API-sleutel — de limieten van een sleutel staan los van het anonieme plafond.
• Respecteert een openbare bewerking de rechten van de gebruikers van de app? Een anonieme partij is geen gebruiker — er is geen gebruikersgebonden gegevensbereik om toe te passen. Stel in openbare bewerkingen alleen gegevens beschikbaar die werkelijk van iedereen mogen zijn.