2010-04-16 11 views
8

Mam serwer oparty na Railsach z kilkoma usługami REST i interfejsem internetowym opartym na Railsach, który współdziała z serwerem przy użyciu ActiveResource. Ten sam serwer jest używany przez innych klientów (np. Telefon komórkowy). Muszę wygenerować dokumentację interfejsu REST. Muszę podać adres URL usługi, strukturę wejścia/wyjścia i strukturę błędów dla każdej usługi.Samoobszarowy interfejs REST

Idealnie, chciałbym użyć przechwytywacza po stronie serwera, który będzie dokumentować usługę w oparciu o istniejący ruch. Zastanawiam się, czy jest jakiś klejnot do zrobienia tego.

Odpowiedz

1

Podczas stosowania stylu architektonicznego REST nie trzeba dokumentować interfejsu.

Umowa między klientem a serwerem jest ustalana na podstawie używanego rodzaju nośnika, jeśli potrzebna jest jakakolwiek inna dodatkowa dokumentacja, użytkownik nie jest REST.

Tak więc, zamiast martwić się o dokumentowanie swojej usługi, należy umieścić całą swoją uwagę opisową w dokumentacji typów multimediów. Wiedza na temat typów mediów jest wszystkim, co jest niezbędne do wdrożenia klientów na twoim serwerze.

+3

To prawda, że ​​usługi REST nie potrzebują WSDL jak klasyczny web-service, ale potrzebuję schemat. Klient musi znać adres URL, metodę HTTP, strukturę dokumentu wejściowego, strukturę odpowiedzi i strukturę błędów dla każdego działania. To, o co proszę, jest podobne do dokumentacji API, którą widzisz dla interfejsu YouTube RESt API, lub interfejsu API REST dla Twittera. Np .: http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-users%C2%A0show –

+1

Można argumentować, że nie ma potrzeby określania metody HTTP dla usługi REST, ponieważ może ona zostać wykorzystana z rodzaju operacji. Ale w praktyce, jeśli masz niestandardową operację (tj. Operację non CRUD), lepiej udokumentować oczekiwaną metodę HTTP. –

+1

Z wyjątkiem identyfikatora URI do wprowadzania aplikacji (może istnieć wiele identyfikatorów URI pozycji, BTW) wszystkie aspekty, o których wspominasz, muszą być opisane przez specyfikację typu nośnika. Usługa nie wymaga wcale opisu. Na przykład rozwijasz klientów AtomPub na podstawie RFC5023, a nie na podstawie opisu API. –

2

Darrel i Jon są poprawni, chciałbym dodać, że interfejs API powinien być wykrywalny w katalogu głównym. Należy przedstawić działania dotyczące odczytu i zapisu.

Wyjazd rozmowa Jon Moore'a do dalszej dyskusji na http://vimeo.com/20781278