Authentication

Introduktion

For at interagere med shoppens GraphQL API, skal du angive passende adgangsoplysninger til godkendelse med hvert HTTP request. Fremgangsmåden til opsætning og anskaffelse af disse oplysninger er beskrevet i de følgende afsnit.

Administration af OAuth klienter

For at generere tokens til godkendelse med OAuth2, kræves at du opretter en OAuth klient i shoppens administration. Du finder indstillingerne for OAuth under Indstillinger > API:

Klik på knappen Opret API-klient.

Bemærk: API-klienten udløber aldrig. Adgangstoken er gyldig i 24 timer.

Indtast det ønskede navn og klik Gem:

I API-oversigten vil den nye klient nu være synlig:

• Klik på klientens navn for, at redigere den.
• Klik på Regenerer for at generere en ny secret (klient kode).
• Klik på Tilbagekald for at deaktivere klienten.

Generering af API-adgangstoken

For at generere et adgangstoken, foretages et HTTP POST request med Klient ID og Klient kode (secret) som oprettet i shoppens administration:

   curl --request POST \
        --data 'grant_type=client_credentials&client_id=[client-id]&client_secret=[client-secret]&scope=' \
        https://[tenant].mywebshop.io/auth/oauth/token
    

Foretag godkendte anmodninger

Efter klienten har modtaget et API-adgangstoken, er det nu muligt at lave godkendte requests til GraphQL API. Requests indeholder en header: Authorization: Bearer {access_token} hvor {access_token} byttes ud med det genererede adgangstoken.

Bemærk: Adgangstoken er gyldig i 24 timer.

Her er et eksempel på et request med adgangstoken:

   curl -H 'Accept: application/json' \
        -H 'Content-Type: application/json' \
        -H "Authorization: Bearer [token]" \
        --data-binary '{"query":"query{orders{data{id}}}","variables":{},"operationName":null}' \
        https://[tenant].mywebshop.io/api/graphql
    

Foretag godkendte anmodninger med Postman

I stedet for at benytte curl til, at foretage forespørgsler kan du også benytte Postman, der giver mulighed for, at arbejde i en grafisk brugerflade, hvor du kan gemme dine forespørgsler til fremtidig brug.

Når du benytter Postman med shoppens API får du automatisk adgang til en grafisk oversigt over alle tilgængelige ressourcer, hvilket også er en god mulighed for, at søge og afklare, hvilke emner du kan tage fat i. Og alt efter, hvilket endpoint du benytter kan du tilgå både Public API (publiceret funktionalitet) og Experimental API (funktionalitet, der endnu er under udvikling).

Access token link og endpoints

Du skal bruge følgende URL'er til, at foretage autorisation og kald mod shoppens API. I guiden herunder viser vi hvor og hvornår du skal bruge URL'erne.

• OAuth2 access token URL: https://shopXXXXX.mywebshop.io/auth/oauth/token
• Public API endpoint: https://shopXXXXX.mywebshop.io/api/graphql
• Experimental API endpoint: https://shopXXXXX.mywebshop.io/api/graphql/experimental

Bemærk: Indsæt dit eget shopnummer, hvor der står shopXXXXX i eksemplerne. Du kan downloade Postman her.

Sådan gør du

Før vi kan foretage autoriserede kald til shoppens API kræves en godkendelse i form af et Token - en nøgle, der gør os i stand til, at blive identificeret som brugere af API'et. Så det første vi gør i Postman er, at bede shoppens API om at godkende os med det ID og Secret, som findes på API-klienten i shoppen under Indstillinger > API. Herefter kan vi benytte vores Token som Postman automatisk gemmer på den forespørgsel vi arbejder med.

1. Start Postman og klik på New for, at starte en ny forespørgsel. Vælg GraphQL i dialogen:
   

   

2. Klik på fanen Authorization og vælg OAuth 2.0 i dropdown listen:
   

   

3. Rul ned i sektionen til højre, til du når Configure New Token (indholdet felterne længere oppe kan du se bort fra):
   

   

   1. Token Name: Angiv et meningsfuldt navn. Du kan f.eks. benytte det samme navn som du har benyttet til API-klienten i shoppen.
   2. Grant type: Vælg Client Credentials, da vi foretager en autorisation af vores forbindelse.
   3. Access Token URL: Indsæt dit autorisationslink til shoppen (se eksemplet længere oppe på denne side).
   4. Client ID: Her skal du indsætte det Client ID, som findes på din API-klient i shoppen.
   5. Client Secret: Indsæt din Secret, som findes på din API-klient i shoppen.
   • De resterende felter kan du se bort fra.

     Her er et eksempel på, hvor du finder Client ID og Secret i shoppen:

     

4. Når du har udfyldt de relevante felter skal du rulle ned på siden og klikke på Get New Access Token:
   
   
5. Hvis oplysningerne matcher og linket til autorisation er korrekt vil denne dialog vises kortvarigt:
   
   
6. Herefter åbnes følgende dialog med dit Access Token. Klik på knappen Use Token for at tilknytte det til din nuværende forespørgsel i Postman:
   
   
7. Herefter skal du gå til fanebladet Query, og indsætte shoppens endpoint i feltet øverst (se eksempel længere oppe i denne artikel). Dette vil automatisk publicere sektionen nedenunder med de ressourcer du har til rådighed via det indsatte endpoint:
   
   
8. Vælg et eller flere emner ved, at sætte markering og klik på Query for, at foretage en forespørgsel op mod API'et. Resultatet vil efterfølgende blive vist i sektionen nederst i Postman:
   
   

Husk, at du kan benytte Experimental endpoint til, at arbejde med funktionalitet der endnu ikke er publiceret i Public API'et. Du kan se eksempler på endpoints længere oppe i artiklen.

Hent ordredata via ordre ID

I dette eksempel har vi sat markering ved orderById ved først, at søge på order. Da dette er en forespørgsel, som forventer et ordre ID giver Postman mulighed for, at indtaste ID'et på variablen direkte på siden. Herefter klikker vi på Query, og får den pågældende ordre ud i vores svar fra API'et:

I dette eksempel findes ordren ikke, og vi får null retur. Vi kan se på serverens responsekode, som er 200, at vores forespørgsel er blevet fuldført:

Hvis du laver din egen integration til shoppens API kan du med et eksempel som dette få en indsigt i, hvordan dit kald skal formateres i din egen kode ved, at studere, hvad Postman sender til API'et. Og ligeledes ved, at studere de værdier du får tilbage fra API'et.