Jak reprezentować (wyliczać) typy w publicznym interfejsie API

32

Pracuję nad prostym interfejsem API, którego chcę używać dla własnego klienta i aby był otwarty dla publiczności w przyszłości. Mam obiekty „Przedmiot”, które mogą mieć różne „typy”. Typ jest „enum typedef C”, na razie mam:

typedef enum {
    ItemTypeBool,
    ItemTypeNumber,
    ItemTypeDate,
} ItemType;

(Mogę dodać trochę w przyszłości)

Zastanawiam się, czy raczej powinienem przenieść to jako liczby całkowite lub jako zdefiniowane „ciągi”. JSON będzie:

Dla liczb całkowitych:

{
  "name": "The name",
  "type": 0,
   ...
}

Dla ciągów:

{
  "name": "The name"
  "type": "boolean"
   ...
}

Zastanawiam się, czy jest na to najlepsza praktyka. Zachowanie liczby całkowitej nieco uprości kod i zmniejszy przepustowość, ale programiści łatwiej zapamiętają. Pamiętam, że pracowałem nad projektem i musiałem pamiętać 1 = obraz, 2 = audio, 3 = HTML, ... co nie ma żadnego sensu.

Pytam więc, czy znasz jakiś inny aspekt, który powinienem rozważyć.

api patterns-and-practices enum Julien
źródło
Czy oczekujesz, że użytkownicy często będą ręcznie edytować JSON?
James

Odpowiedzi:

39

Podaj ciągi znaków. Liczby są bez znaczenia. Nie używasz ich we własnym kodzie, prawda (zawijasz wartości wyliczeniowe, które są w zasadzie ciągami znaków) - po co karać użytkownika za używanie tych liczb?

Jedyny profesjonalista, jeśli ujawnisz liczby - łatwiej je przeanalizować. Ale hej, kogo to obchodzi. Zadbaj o klientów API.

Jeśli podasz ciągi znaków - łatwiej dla klientów; nigdy nie będę musiał mówić rzeczy takich jak „4 zostały wycofane na korzyść 17”; nieco trudniejsze parsowanie w twoim imieniu, ale to dobrze.

Nie dostarczaj obu: jako użytkownik, zastanawiam się

  • z którego korzystam? Obie? [do czytania dokumentów]
  • dlaczego są dwa sposoby na powiedzenie tego samego? czy są subtelnie różne? [do czytania dokumentów]
  • co jeśli podam oba, a wystąpi niedopasowanie? będzie narzekać? czy ktoś będzie miał pierwszeństwo? Który? [do czytania dokumentów]

Jak widzisz, czytam dużo dokumentów bez powodu.

iluxa
źródło
Zgadzam się z @iluxa
portforwardpodcast
1
Co jeśli enum jest oczekiwanym członkiem klasy (obiektu) jako dane wejściowe w wywołaniu rest?
ogier
2

Smyczki.

Jedną z mocnych stron Jsona jest to, że jest czytelny dla człowieka. Podczas debugowania wyjścia za pół roku od teraz „0” nic ci nie powie.

Niektóre frameworki również wykonają automatyczną konwersję. Jeśli go nie używasz - możesz samodzielnie utworzyć konwerter, aby kod pozostał suchy.

To jednak zmienia się w głosowanie.

Evgeni
źródło
1

Najlepsza praktyka zależy od tego, kto korzysta z interfejsu API. Jeśli próbujesz ułatwić życie konsumentowi, powinieneś podać przykładowy kod w C, JAVA, iOS, python, ruby, który może zużywać twoje API. W tych opakowaniach możesz uwzględnić wyliczenie, użyć int w json, a następnie po prostu parsować swoje json w obiekcie z ustawionym wyliczeniem i zwrócić ten obiekt do kodu użytkownika.

Inną rzeczą, którą możesz zrobić, to zapewnić jedno i drugie. na przykład:

{
  "name": "The name",
  "typeId": 0,
  "type": "ItemTypeBool"
   ...
}

Lub możesz użyć type i typeStr w zależności od tego, co najlepiej wygląda w twoim API.

A następnie wyraźnie zaznacz w dokumentacji, że są one zbędne, i to programista decyduje, który jest najlepszy dla ich aplikacji.

Spójrz na json tutaj: https://dev.twitter.com/docs/api/1/get/search Twitter ma przykład dostarczania redundantnych danych (id i id_str), ale to dlatego, że niektórzy klienci json nie mogą analizować długich ints z „liczba” w jsonie i wymaga ciągu, aby uniknąć utraty cyfr

portforwardpodcast
źródło