Come devo costruire una buona (web) API

Question

Ho intenzione di costruire una API per una web app e mi interessa quello che la gente può suggerire come buone pratiche.

Ho già intenzione di fare la versione (versione 1 può solo controllare alcuni aspetti del sistema, la versione 2 è in grado di controllare più, ma questo può avere bisogno di un cambiamento nel modo di autenticazione viene eseguita, che sarebbe incompatibile con la versione 1), e l'autenticazione di essere distinti dagli standard username/password che uso per accedere (se qualcuno fa uso di uno strumento dannoso, non si apre fino alla completa rappresentazione, solo quello l'api consente).

Qualcuno ha altre idee o esempi di siti particolarmente bene Api hai usato?

Answer 1

Leggi l' I Servizi Web RESTful libro, che offrono una buona panoramica di come utilizzare il RESTO, in pratica, e ottenere fino a velocità abbastanza rapidamente per iniziare ora, con un po ' di fiducia.Questo è più utile che solo guardando un API esistenti, perché si discute anche di scelte progettuali e di trade-off.

Answer 2

1) Cuocere il numero di versione direttamente nell'URL, piuttosto che passando come parametro, dal momento che offre una totale libertà di cambiare l'organizzazione del vostro API spazio dei nomi con ogni versione di bump.

2) Mantenere il vostro URL regole di riscrittura (se del caso) come semplice/snello possibile (ma non più semplice), mentre il tuo Url bella come possibile (ma non di più).

3) cercare Sempre il meglio codice di stato HTTP è possibile trovare per ogni risposta (e non dimenticare 202 e 207, per esempio).

4) Implementare fascista parametro logica di convalida, e messaggi di errore informativo.

5) Utilizzare le intestazioni di richiesta HTTP ove opportuno, invece di parametri (come Accettare, per esempio, per consentire ai clienti di specificare i dati desiderati formato di risposta).

6) Organizzare il tuo "sostantivi", in modo che l'Url utilizzato da client diversi gruppi di destinatari sono separati da vicino il "root" del tuo URL albero (questo rende più facile per applicare i meccanismi di autenticazione diversi per i diversi gruppi di destinatari, se necessario, o anche la mappa di diverse parti della tua URL albero a server diversi).

7) Se si sta servendo normali pagine web dello stesso dominio di Api e di utilizzare le stesse credenziali di autenticazione, richiedono un X-Richiesto-Con intestazione le richieste API in modo da evitare XSRF vulnerabiities.

Answer 3

Vorrei prendere un guardare dimostrato Api:

1. API di YouTube
2. API di Twitter

C'è un sacco di discussione su se queste Api sono "buono", ma credo che il loro successo è dimostrato, e sono tutti di facile utilizzo.

Answer 4

Utilizzare RESTO.

RESTful web services architecture è facile da implementare e utilizza la forza e la semantica di HTTP per il quale erano destinati.È risorsa-oriented, come il web stesso.

Amazon Web Services, Google e molti altri offrono RESTO Api per interagire con i loro prodotti.

Answer 5

Utilizzare il RESTO.

Leggere le norme per le Api, o copiare le idee di uno dei più popolari.

Prestare attenzione durante l'autenticazione degli utenti.

Inizio molto, molto semplice.

Costruire un sito web che utilizza le API (anche se non è utile) per controllare le cose di lavoro.Forse si potrebbe creare una versione mobile del sito o qualcosa che ti costringe a utilizzare l'API in un sacco di profondità.