Ustandaryzowanie konstrukcji REST API

Standard

Zasady komunikacji REST API

Status

Data zgłoszenia

Autorzy

Maciej Walczak

Właściciele

Maciej Walczak

Epik

Kontekst

W związku z realizacją coraz większej ilości stron i paneli administracyjnych w technologii REST API, chciałbym ustandaryzować komunikację pomiędzy backendem a frontem. W tej chwili każdy projekt implementuje standard takiej komunikacji po swojemu - część opiera się głownie na kodach HTTP, część używa tylko GET i POST, inne zaś bazują głównie na zwracanych danych.

• Jaki powinien być typ zwracanych danych? TEXT, JSON, XML?

• Wg jakiej konwencji powinny być tworzone nazwy endpointów?

• Jakich typów operacji chcemy używać i do czego? (GET, POST, PUT, DELETE…)

• Czy opierać komunikację na kodach błędów HTTP, w jakim zakresie i jak je interpretować?

• Jak realizować filtrowanie, sortowanie i paginację?

• Jak zapewnić odpowiedni poziom bezpieczeństwa projektowanego API?

• Czy i jak cacheować dane?

• Jak zapewnić wersjonowanie API?

• Jakich narzędzi używać do projektowania i testowania API?

Decyzje

• Komunikacja w formacie JSON

• Stosujemy odpowiednie metody HTTP oraz w przypadku błędów, odpowiednie kody HTTP

• Stosujemy jedną ogólnie przyjętą formę danych zwracanych przez backend do frontu

• W przypadku konieczności przesłania języka lub strefy czasowej przez front do backendu, stosujemy odpowiednie nagłówki HTTP

Konsekwencje