Projektujemy interfejs API RESTful, aby otworzyć informacje o koncie klienta. Mamy reprezentacje zawierające odniesienia do innych zasobów związanych z bieżącym zasobem. Wynika to z wielu najlepszych praktyk, które udało nam się znaleźć w publicznych interfejsach API, a także w opublikowanych materiałach. Reprezentacjami mogą być XML lub JSON.
Na przykład dla zasobu konta mielibyśmy odniesienia do adresów konta, a dla paginowanego zasobu listy, mielibyśmy odniesienia do pierwszej, następnej i poprzednich stron.
Interfejs API został po raz pierwszy zaprojektowany przy użyciu łączy semantycznych, <link title="" rel="" href="" />
jak opisano w książce O'Reilly, i został użyty w interfejsach API przez Netflix i Google. Kiedy przyszedł czas, aby nasi inżynierowie ds. Kontroli jakości napisali pakiet automatyzacji, mieli problemy z deserializacją łączy. Zasugerowaliśmy teraz prostsze elementy łańcucha uri, które były używane w interfejsach API przez Facebooka i Twittera.
Nasi inżynierowie ds. Kontroli jakości od tego czasu rozwiązali swoje problemy z deserializacją, ale nadal mam obawy o łatwość użycia bieżącej specyfikacji API z linkami semantycznymi. Nasz interfejs API będzie używany głównie przez naszych klientów i niektóre podmioty zewnętrzne, a my poszliśmy do REST, ponieważ poprzedni interfejs API XML-RPC był zbyt trudny dla naszych klientów.
tl; dr;
Pytanie:
Czy ktoś, kto zaimplementował semantyczną reprezentację linku, napotkał problemy konsumentów?
Aktualizacja (6/21): Postanowiłem pozostać z linkami semantycznymi i mam nadzieję, że zamieszanie było skrajnym przypadkiem. Postaram się pamiętać, aby odpowiedzieć na pytanie z naszymi doświadczeniami, gdy interfejs API zostanie udostępniony niektórym klientom.
Edycja: dodaj przykłady
Konto semantyczne JSON:
{
"username": "paul",
"links": [
{
"title": "addresses",
"rel": "related",
"href": "http://example.com/account/paul/addresses"
},
{
"title": "history",
"rel": "related",
"href": "http://example.com/account/paul/history"
}
]
}
Konto semantyczne XML:
<account>
<username>paul</username>
<link title="addresses" rel="related" href="http://example.com/account/paul/addresses" />
<link title="history" rel="related" href="http://example.com/account/paul/history" />
</account>
Proste konto JSON:
{
"username": "paul",
"addresses": "http://example.com/account/paul/addresses"
"history": "http://example.com/account/paul/history"
}
Proste konto XML:
<account>
<username>paul</username>
<addresses>http://example.com/account/paul/addresses</addresses>
<history>http://example.com/account/paul/history</history>
</account>
Odpowiedzi:
Wolałbym mieć:
Eliminuje to tablicę i sprawia, że obiekt jest w stanie przejść (aby uzyskać adres konta, np. W JavaScript, można powiedzieć: account.address.href zamiast zapętlać wszystkie linki i znaleźć taki, który wygląda jak adres). Odpowiadający XML:
Co myślisz?
źródło
Sen sieci semantycznej polega na tym, że linki mogą być odkryte automatycznie. Ponieważ trudną częścią jest zrozumienie powiązań i sposób ich wykorzystania, uważam, że informacje semantyczne nie są tak przydatne.
Opieram się nieco na semantycznych formach XML, ponieważ atrybut „rel” ma zdefiniowany mechanizm rozszerzalności pól oddzielonych spacją, a „link” jest dobrze zrozumiany.
Jako konsument takich interfejsów API nie widzę wiele innych różnic.
źródło