Dokumentacja API

System udostępnia interfejs programistyczny do automatyzowania prac oraz integracji z systemami wewnętrznymi Państwa organizacji.

Typ

GraphQL (graphql.org)
Aktualna wersja: 1.1.0

Spis treści

  1. Punkt komunikacji
  2. Uwierzytelnianie
  3. Listowanie
  4. Tworzenie i modyfikowanie
  5. Usuwanie
  6. Struktura stronicowania
  7. Struktura sortowania
  8. Struktura filtrowania
  9. Struktura błędów
  10. Definicje zapytań, mutacji, pól oraz dyrektyw

Punkt komunikacji

Zapytania HTTPs do API aplikacji muszą być kierowane na adres:
https://c.api.talpasmart.com/api/public/
Cała komunikacja odbywa się poprzez protokół HTTPs zapytaniami, w których ciele znajdują się zapytania, definicje lub mutacje GraphQL, a w nagłówkach między innymi token uwierzytelniający.

Uwierzytelnianie

W celu autoryzacji należy w zapytaniu HTTPs wysłać nagłówek z tokenem autoryzacji. Generuje się go w aplikacji i jest przypisany dla każdego konta. Token dziedziczy uprawnienia po użytkowniku.

Przykładowy request:
„`plaintext
POST /graphql HTTP/1.1
Host: ext.api.talpasmart.com
User-Agent: ExampleApp/1.0.0
Content-Type: application/json
Authorization: dbsuifmriugreng9ufh92hf92hf92fn392un9unsiucsbciskjb
Accept: /
Content-Length: 113

Listowanie obiektów

Listowanie obiektów odbywa się za pośrednictwem zapytań w GraphQL, które posiadają stronicowanie, sortowanie i filtrowanie.

Przykładowe zapytanie:

query {
  firms(name_Icontains: "Testowa") {
    totalCount
    results(limit: 5, offset: 0, ordering: "name, -id") {
      id
      name
    }
  }
}

Powyższy przykład prosi system o zwrócenie listy pięciu firm mających w nazwie „Testowa” zaczynając od pierwszej, posortowane w pierwszej kolejności po nazwie rosnąco, a następnie po identyfikatorze malejąco. Chcemy z tego obiektu tylko dwa pola: identyfikator oraz nazwa. Dodatkowo prosimy o ilość polem totalCount.

Tworzenie i modyfikowanie

Modyfikacje obiektów odbywają się przez mutacje. Każda mutacja w systemie zbudowana jest z minimum 3 pól:

  • errors – przekazywane są tu błędy wykonania mutacji
  • ok – wartość logiczna informująca, czy mutacja przebiegła pomyślnie
  • <nazwa wejścia> – zależnie od mutacji, inna nazwa pola o innym typie; tu przekazujemy dane wejściowe do mutacji.

Przykładowa definicja mutacji:

input MerchandiseUpdateGenericType {
    id: ID!
    defaultAddressPostalcode: String
    defaultAddressString: String
    defaultLat: Float
    defaultLon: Float
    displayName: String!
    ...
}

input MerchandiseCreateGenericType {
    defaultAddressPostalcode: String
    defaultAddressString: String
    defaultLat: Float
    defaultLon: Float
    displayName: String!
    ...
}

type MerchandiseSerializerMutation {
    errors: [ErrorType]
    merchandise: MerchandiseType
    ok: Boolean
}

merchandiseCreate(newMerchandise: MerchandiseCreateGenericType!): MerchandiseSerializerMutation

Przykładowa mutacja tworząca obiekt:

# Mutacja
mutation ($data: MerchandiseCreateGenericType!) {
  merchandiseCreate(newMerchandise: $data) {
    ok
    errors {
      messages
      field
    }
    merchandise {
      id
    }
  }
}

# Zmienne 
{
	"data": {
		"displayName": "Tak!",
		"lastLat": 15.0000,
		"lastLon": 52.0000
	}
}

Powyższy przykład wstawia nowy obiekt do towarów. Definiujemy, że chcemy dostać jego id po operacji wstawienia oraz informacje, czy wszystko poszło dobrze (ok) oraz czy są jakieś błędy w polach (errors).

Przykładowa mutacja aktualizująca obiekt:

# Mutacja
mutation ($data: MerchandiseUpdateGenericType!) {
  merchandiseUpdate(newMerchandise: $data) {
    ok
    errors {
      messages
      field
    }
    merchandise {
      displayName
    }
  }
}

# Zmienne 
{
	"data": {
		"id": 12,
		"displayName": "Tak 12",
		"lastLat": 15.0000,
		"lastLon": 52.0000
	}
}

Powyższy przykład aktualizuje obiekt o identyfikatorze 12 i prosi o nazwę po modyfikacji. Obsługa błędu wygląda dokładnie tak samo jak w przypadku dodawania nowego.

Usuwanie

Usuwanie obiektów odbywa się przez mutacje. Struktura jest dokładnie taka sama jak w przypadku tworzenia czy aktualizacji.

Przykładowa definicja mutacji usuwającej:

merchandiseDelete(id: ID!): MerchandiseSerializerMutation

Przykładowa mutacja usuwająca obiekt:

mutation {
  merchandiseDelete(id: 12) {
    ok
    errors {
      messages
      field
    }
  }
}

Powyższy przykład usuwa obiekt z towarów o id 12 z obsługą błędów.

Struktura stronicowania

Listy obiektów w systemie są zdefiniowane w standaryzowanej formie posiadającej zawsze pola:

  • totalCount: Int – określa liczbę elementów pasujących do zapytania
  • results(limit: Int = 20, offset: Int, ordering: String): [<odpytywany typ>] – lista obiektów
  • limit: Int = 20 – maksymalna liczba elementów na stronie, max. 50 elementów
  • offset: Int – przesunięcie
  • ordering: String – sortowanie opisane poniżej.

Przykładowa definicja:

type AttachmentListType {
    results(
        limit: Int = 20,
        offset: Int,
        ordering: String
    ): [AttachmentType]
    totalCount: Int
}

Struktura sortowania

Sortowanie w aplikacji opiera się o ciąg znaków mówiący, jak dane mają zostać posortowane. Nazwy pól do sortowania muszą zostać przekonwertowane z camelCase do snakeCase. Aby zmienić kierunek sortowania, przed nazwą pola dodajemy „-”.

Przykład sortowania:

display_name, -created_at

Powyższy przykład mówi: sortuj po display_name rosnąco, a następnie po created_at malejąco.

Struktura filtrowania

Aplikacja umożliwia filtrowanie list wraz z operatorami. Każde zapytanie ma podaną listę filtrów, które składają się z dwóch członów: <nazwa_pola>_<operator>. Filtr podajemy w zapytaniu o pole jako parametr, np. query { firms(name_Icontains: "Testowa") }.

Przykładowe operatory:

  • Icontains – pole zawiera ciąg znaków bez rozróżnienia wielkości znaków
  • Istartswith – pole zaczyna się od ciągu znaków bez rozróżnienia wielkości znaków
  • Iendswith – pole kończy się ciągiem znaków bez rozróżnienia wielkości znaków
  • Isnull – pole jest puste (wartość true lub false)
  • Lte – wartość pola jest mniejsza lub równa podanej wartości
  • Gte – wartość pola jest większa lub równa podanej wartości
  • Lt – wartość pola jest mniejsza niż podana wartość
  • Gt – wartość pola jest większa niż podana wartość
  • BRAK – wartość pola jest równa podanej wartości.

Struktura błędów

Błędy w systemie pojawiają się na dwóch poziomach aplikacji. Mogą zostać zwrócone błędy dla konkretnego pola lub błędy ogólnego przeznaczenia.

Definicja błędu:

type ErrorType {
    field: String!
    messages: [String!]!
}

Definicje zapytań, mutacji, pól oraz dyrektyw

Wszystkie potrzebne definicje zostały ujęte w wygodnej formie na stronie: https://talpasmart.com/dokumentacja/