API best practices

1. Obmedzte duplicitné volanie požiadaviek na API.
2. Prístupové tokeny obmedzte na konkrétne IP adresy, z ktorých prebieha volanie na API.
3. Pravidelne mažte nepoužívané prístupové tokeny v administrácii.
4. Pre volanie API používajte verejný názov domény v URL a správny protokol. Zamedzíte tým zbytočným HTTP presmerovaním.
   Miesto https://vasa-stranka.flox.sk/api/graphql použite
   https://www.vasa-domena.sk/api/graphql
5. Pre obmedzenie prístupu k funkciám API priraďte token používateľom s obmedzenými právami.
6. Pri pravidelnej aktualizácii sa pýtajte len na údaje, ktoré skutočne vyžadujete. Uveďte do dotazu presný zoznam parametrov, ktoré sú v odpovedi potrebné pre ďalšie spracovanie alebo využite zápis pomocou vlastného fragmentu (viď. príklad č.1).
7. Preddefinované fragmenty môžete kombinovať so špecifickým zoznamom ďalších parametrov.
8. Zložité alebo obsiahle otázky rozdeľte do samostatných poddotazov a požiadavky spracujte postupne. Napríklad pokiaľ požadujete kompletnú štruktúru kategórií e-shopu a zároveň produktové dáta. Spracujte kategórie a produkty oddelene.
9. Pri listovaní zoznamov a zložitej štruktúre odpovede používajte menšie hodnoty pre stránkovanie (parameter limit nastavte na menšiu hodnotu ako 30). To platí pre metódy getProductList, getOrderList, getInvoiceList atď. ak požadujete aj previazané dáta v hlbších úrovniach.
10. Pri vykonávaní mutácie je vhodné do odpovede zahrnúť práve menené parametre. Tým zároveň skontrolujete, že operácia prebehla správne. Napríklad pri zmene statusu objednávky je vhodné sa rovno opýtať na jej status v odpovedi (viď. príklad č. 2)

Príklady:

1. Definícia vlastného fragmentu poslaného spolu s dotazom

query {
      getOrderList(lang_code: "SK", params: { order_by: pur_date, sort:DESC, limit:30, cursor:0}) {
           pageInfo{
               ... _PageInfo
          }
          data{
              ... MyOrderData # using your own fragment
          }
    }
}
# custom fragment definition for specific order data
fragment MyOrderData on Order {
      order_num
      pur_date
      sum {
           formatted
      }
}

POST /api/graphql HTTP/1.1
Host: vasastranka.sk
BW-API-Key: Token Ijw..................gKsB7
Content-Type: application/json
Cookie: SSID=27s5cke5yr78c441203a01bbur
Content-Length: 500


{"query":"query {\r\n getOrderList(lang_code: \"SK\", params: { order_by: pur_date, sort:DESC, limit:30, cursor:0}) {\r\n pageInfo{\r\n ... _PageInfo\r\n }\r\n data{\r\n ... MyOrderData # using your own fragment\r\n }\r\n }\r\n}\r\n# custom fragment definition for specific order data\r\nfragment MyOrderData on Order {\r\n order_num\r\n pur_date\r\n sum {\r\n formatted\r\n }\r\n}","variables":{}}

2. Zmena statusu objednávky. Odpoveď obsahuje na kontrolu menené parametre

mutation {
     changeOrderStatus(order_num: "2302120", status_id: 4){
         #request the changed parameters in mutation response
         order_num
         status {
              id
              name
         }
     }
}

POST /api/graphql HTTP/1.1
Host: vasastranka.sk
BW-API-Key: Token Ijw..................gKsB7
Content-Type: application/json
Cookie: SSID=27s5cke5yr78c441203a01bbur
Content-Length: 281


{"query":"mutation {\r\n changeOrderStatus(order_num: \"2302120\", status_id: 4){\r\n #request the changed parameters in mutation response\r\n order_num\r\n status {\r\n id\r\n name\r\n }\r\n }\r\n}","variables":{}}

3. Zápis dotazu s využitím fragmentov a samostatných parametrov

query {
       getProduct(product_id: "26049"){
              # fragment _Product contains "attribute_category" with only "id" and "title" params
              ... _Product
              attribute_category {
                    id
                    title
                    # in the query you can override the parameter and spoecify different parameters
                    description
             }
      }
}

POST /api/graphql HTTP/1.1
Host: vasestranka.cz
BW-API-Key: Token Ijw..................gKsB7
Content-Type: application/json
Cookie: SSID=27s5cke5yr78c441203a01bbur
Content-Length: 481


{"query":"query {\r\n getProduct(product_id: \"26049\"){\r\n # fragment _Product contains \"attribute_category\" with only \"id\" and \"title\" params\r\n ... _Product\r\n attribute_category {\r\n id\r\n title\r\n # in the query you can override the parameter and specify different parameters\r\n description\r\n }\r\n }\r\n}","variables":{}}