Dette dokumentet inneholder forslag til standarder for APIer basert på beste praksis.
For API-er som skal syndikere data, vurder flere vanlige bruksmåter:
Aldri utgi et API uten versjonstall. Sett versjonsnummeret til API-et i URLen.
Versjoner skal være heltall med prefiksen 'v' foran, ikke desimaltall. For eksempel:
Vedlikehold API-et minst en versjon tilbake.
Benytt en opplagt mekanisme, slik at kundene enkelt kan rapportere problemer, og stille spørsmål om API-et.
Ved bruk av f.eks GitHub for API koden, bruk den tilhørende "issue trackeren" der. I tillegg, legg ved en e-post adresse for direkte, ikke offentlig henvendelser.
Bruk en enkel mekanisme slik at klientene kan følge endringer for API-et.
Vanlige måter å håndtere dette på, er ved bruk av e-post lister eller en dedikert utvikler blog med en RSS-strøm.
Et "endepunkt" er en kombinasjon av to ting:
GET eller POST)/artikler)Informasjon kan bli sendt til et endepunkt på følgende måter:
?year=2015)X-Api-Key: nøkkel)Når vi snakker om "RESTful" i disse dager, mener vi egentlig å lage enkle, intuitive endepunkter som representerer unike funksjoner i API-et.
Generelt:
Noen eksempler på disse prinsippene i aksjon:
Ikke bland sammen entall og flertall substantiver.
Hold det enkelt ved å bare bruke flertall substantiver for alle ressurser.
HTTP-verb, eller metoder, skal bli brukt i samsvar med definisjonene under HTTP/1.1 standarden.
Her er et eksempel på et HTTP-verb kart for opprette, lese, oppdatere, og slette operasjoner i en bestemt kontekst:
| HTTP METHOD | POST | GET | PUT | DELETE |
|---|---|---|---|---|
| CRUD OP | CREATE | READ | UPDATE | DELETE |
| /frogs | Create new frogs | List frogs | Bulk update | Delete all frogs |
| /frogs/1234 | Error | Show Bo | If exists, update Bo; If not, error | Delete Bo |
JSON er en utmerket, bredt støttet transport format, egnet for de fleste API-er.
Bruk av JSON, og bare JSON, er i praktisk standard for API-er. Det reduserer kompleksitet for både API-leverandør, og forbruker.
Generelle JSON retningslinjer:
camelCase for nøkler. Ulike språk benytter ulike praksiser. JSON bruker camelCase, ikke snake_case.Bruk ISO 8601 i UTC for både forespørsler og svar.
For datoer ser det slik ut 2015-02-27. For fullstendige tidspunkt 2015-02-27T10:00:00Z.
Dette datoformatet brukes over hele nettet, og setter hvert felt i en konsistent rekkefølge.
Disse standardene tar ikke stilling til om ikke å bruke API-nøklene.
Men hvis nøklene brukes til å administrere, og godkjenne API-tilgang, bør API tillate noen form for uautorisert adgang, uten nøkler.
Dette gjør det mulig for nykommere å eksperimentere med API i demo miljøer og med enkle curl /wget forespørsler.
Vurder om dette er produktets mål å tillate et visst nivå av normal bruk i produksjon av API-et, uten håndheving avansert registrering av klienter.
Håndter alle feil (inkludert uoppfangede unntak), og returner det i en datastruktur i samme format som resten av API-et.
Feilmeldinger må ha med en HTTP status kode, en melding til utviklere, melding for sluttbrukeren (når det er hensiktsmessig), en intern feilkode (som henviser til en spesifisert intern ID), og en link hvor utvikleren kan finne mer info. For eksempel:
{
"status": 400,
"developerMessage": "Verbose, plain language description of the problem. Provide developers
suggestions about how to solve their problems here",
"userMessage": "This is a message that can be passed along to end-users, if needed.",
"errorCode": "444444",
"moreInfo": "http://www.example.gov/developer/path/to/help/for/444444,
http://drupal.org/node/444444",
}Eksempler på HTTP-svarkoder
HTTP-svar med feilinformasjon bør bruke en 4XX statuskode for å indikere en svikt på klientsiden (for eksempel ugyldig autorisasjon eller en ugyldig parameter), og en5XX statuskode for å angi en svikt på serversiden (for eksempel et uoppfanget unntak).
Hvis sidenummerering er nødvendig for å navigere datasett, bruk den metoden som er mest fornuftig for API-ets data.
Vanlige parametere:
page ogper_page. Er intuitivt for mange bruksmåter. Linker til "side 2" vil kanskje ikke alltid inneholde de samme dataene.offset og limit. Denne standarden kommer fra SQL-database verden, og er et godt alternativ når du trenger stabile permalinks til resultat-settet.since and limit. Få alt "siden" noen ID eller tidsstempel. Nyttig når det er en prioritert oppgave å la kundene effektivt være synkronisert med data. Vanligvis krever det at resultatsettes rekkefølge er stabil.Metadata:
Inkluder nok metadata så klientene kan kalkulere hvor mye data det er, og hvordan man eventuelt skal hente det neste datasettet med resultater.
Et eksempel på hvordan dette kan være implimentert:
{
"results": [ ... actual results ... ],
"pagination": {
"count": 2340,
"page": 4,
"per_page": 20
}
}Nye API-er må bruke og kreve HTTPS kryptering (med TLS/SSL). HTTPS gir:
HTTPS bør konfigureres ved hjelp av moderne beste praksis, herunder koder som det støtter forward secrecy, og HTTP Strict Transport Security. Dette er ikke uttømmende: Bruk verktøy som SSL Labs til å vurdere API-ets HTTPS konfigurasjon.
For et eksisterende API som går over vanlig HTTP, er første skritt å legge til HTTPS-støtte, og oppdatere dokumentasjonen til å erklære det standard, bruk det i eksempler osv.
Deretter vurder muligheten til å deaktivere eller omdirigere HTTP forespørsler. Se GSA/api.data.gov#34 for en diskusjon angående noen av utfordringene ved overgangen fra HTTP->HTTPS.
For bedre ytelse anbefaler vi å bruke gzip-komprimering av API-svarene.
Bruk bare UTF-8.
Forvent tegn med "smarte anførselstegn" i API-resultatet, selv om de ikke er forventet.
Et API skal fortelle klientene at det forventes UTF-8 ved å inkludere en karaktersett notasjon i Content-Type header for svaret.
Et API som returnerer JSON må bruke:
Content-Type: application/json; charset=utf-8For at klienter skal kunne bruke et API fra innsiden i nettlesere, må API-et aktivere CORS.
For den enkleste og mest vanlige bruksmåten, der hele API-et bør være tilgjengelig fra innsiden av nettleseren, aktivering av CORS er så enkel som å inkludere denne HTTP header i alle svarene:
Access-Control-Allow-Origin: *Det er støttet av alle moderne nettlesere, og vil bare virke i JavaScript klienter som f.eks jQuery.
For mer avansert konfigurasjon, se på W3C spesifikasjonene eller Mozilla's veiledning.
HTTP tilbyr et innebygd mellomlagrings -rammeverk!
Det kan gjøres på to måter: ETAG og Last-Modified
ETAG
Last-Modified
Et API er bare så god som sin dokumentasjon.
Dokumentasjon skal være enkelt å finne, på en nettside som er offentlig tilgjengelig.
Eksemplene bør inneholde fulle forespørsler, og svar.
Dette prosjektet er lisensiert som CC0 1.0 Universal public domain dedication.
Alle bidrag til dette prosjektet vil bli lansert under CC0. Ved å sende en pull request, eller på annen måte være delaktig i utviklingen, godtar du å overholde denne fraskrivelsen av opphavsretten.