Ho bisogno di scrivere la documentazione di un servizio RESTful. Qualcuno sa di una documentazione molto ben scritta per un servizio RESTful che potrei usare come modello per il mio?Esempio di un servizio RESTful ben documentato
Grazie.
Il Twitter Api documentation è il migliore che abbia mai incontrato.
Link ai documenti API di Twitter modificati - [https://dev.twitter.com/rest/public](https://dev.twitter.com/ riposo/pubblico) – GuirNab
Lo Readability API è stato lodato di recente su Twitter.
Disclosure: Sono un parter di Arc90, i creatori di Readability e un investitore in Readability.
API of CouchDB, "il" database RESTful.
Si noterà che il documento è strutturato per risorsa anziché per metodo, rendendolo più orientato alle risorse rispetto alla maggior parte delle documentazioni API ben note.
Prova rest-tool.
Segue un approccio agnostico alla scrittura delle specifiche. Fornisce un'implementazione simulata istantanea e test unitari automatizzati per le API RESTful off the shelf.
I servizi vengono specificati tramite i file YAML ei dati di esempio possono essere posizionati accanto ai descrittori. È possibile trovare uno schema JSON aboultare il formato del file descrittore service.yml. Questo può essere usato come una gilda, ma è estendibile su richiesta.
È possibile consultare la documentazione Zoho Subscriptions API. Questo documento di layout a 3 colonne è strutturato in base alle risorse e presenta richieste e risposte di esempio per ogni endpoint.
Divulgazione: faccio parte del team di abbonamenti Zoho.
Come posso scrivere uno come questo? Hai usato qualche strumento per questo? Per favore suggeriscimi, sto andando a costruire la nostra documentazione API. – theGamblerRises
Avete sentito parlare di http://swagger.io/? Genera una documentazione molto utile (e piacevole) per un'API REST.
Provalo. Lo consiglio davvero.
Controllare la documentazione REST API Documentation Best Practices per documentare il servizio RESTful. Il documento copre tutti gli aspetti. Ecco un frammento di esso.
Titolo: Mostra tutti gli utenti.
URL:/utenti o/Users/id: o/utenti id =: id
Metodo:? GET | POST | DELETE | PUT
URL Parametri:Required:id = [numero intero] OROptional:photo_id = [alfanumerico]
dati Parametri: {u: {e-mail: [stringa], nome: [stringa], current_password: [alfanumerico] Password : [alfanumerico], password_confirmation: [alfanumerico]}}
codici di risposta: Success (200 OK), Bad Request (400), non autorizzate (401)
qual è la differenza tra i tipi di dati "stringa" e "alfanumerico"? – mre
hai trovato uno? Sono interessato a sentire quale, se lo hai fatto. –
Un servizio RESTful non necessita di una documentazione scritta molto buona. :) –
Ogni API ha bisogno di una buona documentazione scritta – kralco626