Wypróbuj API

Po pomyślnym zainstalowaniu Deenruv lokalnie zgodnie z przewodnikiem instalacji, pora wypróbować API!

GraphQL Playground

Serwer Deenruv zawiera GraphQL Playground, który pozwala eksplorować API oraz uruchamiać zapytania i mutacje. To świetny sposób na poznanie API i zrozumienie, jak ono działa.

W tym przewodniku będziemy używać GraphQL Playground do uruchamiania zapytań i mutacji w Shop API i Admin API. Na każdym kroku wklej zapytanie lub mutację do lewego panelu Playground, a następnie kliknij przycisk "Play", aby je uruchomić. Odpowiedź zobaczysz w prawym panelu.

Shop API

Shop API to publiczne API używane przez aplikację sklepu.

Otwórz GraphQL Playground pod adresem http://localhost:6100/shop-api.

Pobierz listę produktów

Zacznijmy od zapytania (query). Zapytania służą do pobierania danych. Wykonamy zapytanie, aby pobrać listę produktów.

query {
  products {
    totalItems
    items {
      id
      name
    }
  }
}

Zwróć uwagę, że odpowiedź zawiera tylko te właściwości, o które poprosiliśmy w zapytaniu (id i name). To jedna z kluczowych zalet GraphQL — klient może określić dokładnie, jakich danych potrzebuje, a serwer zwróci tylko te dane!

Dodajmy kilka kolejnych właściwości do zapytania:

query {
  products {
    totalItems
    items {
      id
      name
      slug
      description
      featuredAsset {
        id
        preview
      }
    }
  }
}

Powinieneś zobaczyć, że odpowiedź zawiera teraz właściwości slug, description i featuredAsset. Zauważ, że właściwość featuredAsset jest sama w sobie obiektem i możemy określić, które właściwości tego obiektu chcemy uwzględnić w odpowiedzi. To kolejna zaleta GraphQL — możesz "zagłębiać się" w dane i określać dokładnie, które właściwości chcesz uwzględnić.

Teraz dodajmy argumenty do zapytania. Niektóre zapytania (i większość mutacji) mogą przyjmować argumenty, które umieszcza się w nawiasach po nazwie zapytania. Na przykład pobierzmy pierwszych 5 produktów:

query {
  products(options: { take: 5 }) {
    totalItems
    items {
      id
      name
    }
  }
}

Po uruchomieniu tego zapytania powinieneś zobaczyć tylko pierwszych 5 wyników.

Dodajmy bardziej złożony argument: tym razem przefiltrujemy produkty, których nazwa zawiera ciąg "shoe":

query {
  products(options: {
    filter: { name: { contains: "shoe" } }
  }) {
    totalItems
    items {
      id
      name
    }
  }
}

Dodaj produkt do zamówienia

Teraz przyjrzyjmy się mutacji. Mutacje służą do modyfikowania danych na serwerze.

Oto mutacja, która dodaje produkt do zamówienia:

mutation {
  addItemToOrder(productVariantId: 42, quantity: 1) {
    ...on Order {
      id
      code
      totalQuantity
      totalWithTax
      lines {
        productVariant {
          name
        }
        quantity
        linePriceWithTax
      }
    }
    ...on ErrorResult {
      errorCode
      message
    }
  }
}

Ta mutacja dodaje wariant produktu o ID 42 do zamówienia. Odpowiedź będzie albo obiektem Order, albo ErrorResult. Używamy specjalnej składni zwanej fragmentem, aby określić, które właściwości chcemy uwzględnić w odpowiedzi. W tym przypadku mówimy, że jeśli odpowiedź to Order, chcemy uwzględnić id, code, totalQuantity, totalWithTax itd., a jeśli odpowiedź to ErrorResult, chcemy uwzględnić errorCode i message.

Uruchomienie tej mutacji po raz drugi powinno pokazać, że ilość produktu w zamówieniu wzrosła o 1. Jeśli tak się nie stało, sesja nie jest prawidłowo utrzymywana (zobacz wcześniejszą uwagę w tym przewodniku o ustawieniu request.credentials).

Admin API

Admin API udostępnia wszystkie funkcjonalności potrzebne do zarządzania sklepem. Jest używane przez panel administracyjny, ale może być również używane przez integracje i niestandardowe skrypty.

Otwórz GraphQL Playground pod adresem http://localhost:6100/admin-api.

Logowanie

Większość operacji Admin API jest dostępna tylko dla uwierzytelnionych użytkowników. Dlatego najpierw musimy się zalogować.

mutation {
    login(username: "superadmin", password: "superadmin") {
        ... on CurrentUser {
            id
            identifier
        }
        ... on ErrorResult {
            errorCode
            message
        }
    }
}

Pobierz produkt

Admin API udostępnia znacznie więcej informacji o produktach niż Shop API:

query {
  product(id: 42) {
    enabled
    name
    variants {
      id
      name
      enabled
      prices {
        currencyCode
        price
      }
      stockLevels {
        stockLocationId
        stockOnHand
        stockAllocated
      }
    }
  }
}