API best practices

1. Omezte duplicitní volání požadavků na API.
2. Přístupové tokeny omezte na konkrétní IP adresy, ze kterých probíhá volání na API.
3. Pravidelně mažte nepoužívané přístupové tokeny v administraci.
4. Pro volání API používejte veřejný název domény v URL a správný protokol. Zamezíte tím zbytečným HTTP přesměrováním.
   Místo https://vase-stranka.flox.cz/api/graphql použijte
   https://www.vase-domena.cz/api/graphql
5. Pro omezení přístupu k funkcím API přiřaďte token uživatelům s omezenými právy.
6. Při pravidelné aktualizaci se dotazujte pouze na data, která opravdu vyžadujete. Uveďte do dotazu přesný výčet parametrů, které jsou v odpovědi třeba pro další zpracování nebo využijte zápis pomocí vlastního fragmentu (viz. příklad č.1).
7. Předdefinované fragmenty můžete kombinovat se specifickým výčtem dalších parametrů.
8. Složité nebo obsáhlé dotazy rozdělte do samostatných poddotazů a požadavky zpracujte postupně. Například pokud požadujete kompletní strukturu kategorií e-shopu a zároveň produktová data. Zpracujte kategorie a produkty odděleně.
9. Při listování seznamů a složité struktuře odpovědi používejte menší hodnoty pro stránkování (parametr limit nastavte na menší hodnotu než 30). To platí pro metody getProductList, getOrderList, getInvoiceList atp. pokud požadujete i provázaná data v hlubších úrovních.
10. Při provádění mutace je vhodné do odpovědi zahrnout právě měněné parametry. Tím zároveň zkontrolujete, že operace proběhla správně. Například při změně statusu objednávky je vhodné se rovnou dotázat na její status v odpovědi (viz. příklad č. 2)

Příklady:

1. Definice vlastního fragmentu poslaného spolu s dotazem

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: vasestranka.cz
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. Změna statusu objednávky. Odpověď obsahuje pro kontrolu měněné parametry

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: vasestranka.cz
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ápisu dotazu s využitím fragmentů a samostatných parametru

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 spoecify different parameters\r\n description\r\n }\r\n }\r\n}","variables":{}}