Dokumentacja API RESTful [zamknięta]

Ze względu na charakter RESTful web-based usługi, powinno być dość łatwe do standaryzacja dokumentacji. Powinno wystarczy wymienić dostępne zasoby, odpowiednie Uri, dozwolone metody, content-rodzaje i opis dostępne działania. Czy masz jakieś sugestie?

JEDEN URI do rządzenia nimi wszystkimi

Nigdy nie należy wyliczać Uri zasobów, ponieważ to zachęci klienta do zakodowania tych Uri do kodu klienta. Powoduje to niepotrzebne sprzężenie między Klientem a serwerem. Uri powinny być wykrywane na podstawie nawigacji z głównego Uri usług. Root URI jest jedynym URI, który powinien być udokumentowany. Dokumentacja powinna skupiać się na opisaniu, jakie informacje i linki znajdują się w zwracanych reprezentacjach. Jeśli zaczniesz od reprezentacji zwracanej z głównego URI, możesz opisać media wpisz i jakie są linki, które mogą być zawarte w tym dokumencie.

Alias twojego Uri

Ważne jest, aby użyć pewnego rodzaju aliasu, aby utworzyć warstwę podziału między Klientem a serwerem. Jeśli zastosujesz standard atom: link do definiowania linków, atrybut rel stanie się identyfikatorem. Istnieją jednak inne sposoby definiowania linków, jak na przykład sposób osadzania obrazów w html. Znacznik obrazu może mieć Id i href. Znacznik Id powinien być używany do określ obraz, dla którego chcesz uzyskać dostęp do adresu URL.

Typy mediów definiują Twoje API

Efektem końcowym jest zdefiniowanie wszystkich punktów końcowych w interfejsie API w kontekście jakiejś reprezentacji. Pełne API jest definiowane przez zestaw zwracanych reprezentacji i łącza, które je łączą.

Zmienna przestrzeń URI

Ponieważ te łącza są dostępne dla klienta za pomocą aliasu, dzięki czemu cała struktura adresu URL witryny może być całkowicie zmienna bez wpływu na klienta. To sprawia, że wszystkie niekończące się pytania "Jaki jest najlepszy sposób na strukturę mojego hierarchicznego adresu URL" są praktycznie nieistotne. Możesz spróbować w jeden sposób, a jeśli to nie zadziała, po prostu go zmień, nie złamiesz żadnego kodu klienta ani nie będziesz musiał zmieniać żadnej dokumentacji!

Dynamiczny rozkład

To nie tylko część ścieżki URI, która możesz się zmienić. Możesz też zmienić gospodarza. Wyobraź sobie, że Twoja aplikacja zaczyna uzyskiwać o wiele więcej wykorzystania niż się spodziewałeś, możesz łatwo zmienić host wszystkich zasobów obrazu lub wideo, aby wskazać inny serwer. Możesz nawet zapewnić proste równoważenie obciążenia, zwracając różne hosty. Ponieważ interfejsy API RESTful są bezpaństwowe, tak naprawdę nie ma znaczenia, który serwer odpowie na żądanie. Ta funkcja jest przydatna w tak wielu scenariuszach: przenoszenie materiałów HTTPS na serwer dedykowany, rozmieszczenie geograficzne żądań w oparciu o lokalizację klienta, pionowe partycjonowanie funkcji aplikacji na różnych serwerach.

Explicit protocol

To, że reprezentacja może zwrócić link, nie oznacza, że zawsze będzie. Serwer może zwracać tylko te linki, które są dozwolone na podstawie bieżącego stanu zasobów. Może to być bardzo pomocne, gdy istnieje określony protokół, którego należy przestrzegać podczas interakcji z zasobem serwera. Klient kod nie musi rozumieć zasad protokołu, może po prostu przedstawić użytkownikowi linki, które zostały udostępnione przez serwer.

Nie można autogen ciekawych rzeczy

Powodem, dla którego większość zautomatyzowanych działań związanych z dokumentowaniem usług REST nie jest skuteczna, jest to, że jednolity interfejs eliminuje potrzebę dokumentowania łatwych rzeczy. Gdy zrozumiesz HTTP (zobacz RFC2616), zrozumiesz całą mechanikę API. Wszystko, co pozostało, to naprawdę interesujące informacje specyficzne dla domeny, których nie można wygenerować.

Spójrz na Jasną Stronę, dokumentacja powinna być znacznie krótsza. Każdy dodatkowy dostępny czas należy poświęcić na dostarczenie przykładów poruszania się po interfejsie API dla typowych scenariuszy.