5 passos per crear una api exitosa

És la naturalesa del desenvolupament de programari. Els desenvolupadors creen programari tenint en compte l'usuari final. Sembla bastant senzill, però a vegades aquests usuaris també són companys de desenvolupament. No necessiten coses desglossades per a ells. Ni tan sols necessiten la senzillesa. Tot el que volen és l’accés: una manera d’integrar el vostre programari amb el seu. Aquí és on entra una API (interfície de programació d’aplicacions). Espero destacar cinc passos que podeu fer per crear una API exitosa.

Fes els deures

Quan es tracta de desenvolupament de programari, cap de nosaltres vol reinventar la roda. Arribats a aquest punt, gairebé totes les grans empreses web tenen API per als seus productes de programari. Estudieu aquestes API i proveu de prendre les diferents decisions sobre el disseny que van crear.

Hi ha moltes tecnologies diferents, però la majoria de les API que veureu utilitzaran una interfície RESTful o SOAP. Si esteu a la cerca sobre quina interfície API utilitzeu, us recomano que aneu amb un enfocament RESTful mitjançant el protocol HTTP. És més senzill que SOAP, actualment és més popular i serà més fàcil començar amb l’ús d’un producte de programari basat en web.

Sigui coherent

Una de les coses que més valoren els desenvolupadors és la coherència. Inclou, entre altres coses, l’adreçabilitat, els arguments d’entrada, els formats de sortida i el maneig d’errors.

Quan s'utilitza un enfocament RESTful, hi ha molts esquemes d'anomenament d'URI diferents. Cadascú té els seus partidaris, així que només n'heu de triar i enganxar-hi. El mateix passa amb l’estructura d’entrada i sortida. La majoria d’APIs admeten l’ús de XML i JSON com a formats d’entrada i sortida. Suggeriria donar suport a tots dos, però escollir un format per defecte.

Per a entrada, els vostres requisits d’entrada haurien de tenir un nom coherent i haurien de tenir sentit en el context de la trucada a l’API que esteu fent. Per a la sortida, assegureu-vos que utilitzeu dissenys d’estructura de dades comuns. Si esteu embolicant la sortida d'una trucada API a una Etiqueta XML, penseu fer-ho amb les altres trucades.

És una pràctica habitual incloure algun tipus d’indicador d’estat en les dades de sortida que envieu de nou al client. Quan s'utilitza un enfocament API RESTful, això s'ha de fer mitjançant codis d'estat HTTP. Per exemple, si acabeu de processar una sol·licitud PUT en un objecte de dades existent, el codi d’estat HTTP que inclogueu a la vostra resposta variarà en funció del resultat de la sol·licitud.

En lloc d'un indicador arbitrari que indica l'estat de la trucada, es pot utilitzar un codi d'estat "200 OK" estàndard per significar que la sol·licitud va tenir èxit, mentre que es pot utilitzar un codi d'estat "400 Request Request" per significar que la sol·licitud era mal format. Hi ha força codis d’estat HTTP que es poden utilitzar en situacions diferents.

Utilitzeu OAuth

La majoria de productes de programari comportaran algun tipus d’autenticació d’usuari per tal d’accedir a recursos protegits per a aquest usuari. Quan es tracta d’API, tenir el client recopilar les credencials d’usuari per enviar-lo al vostre servidor és una mala pràctica. Aquí és on entra OAuth.

OAuth proporciona molts avantatges sobre l’autenticació de nom d’usuari / contrasenya de tercers. Sobretot, el client mai té accés a les credencials de l’usuari. L'usuari es redirigeix ​​al vostre servidor quan ell inicia la sessió. Després que l’usuari es connecti al vostre lloc, se’ls redirigeix ​​al client on rebrà un token d’accés per utilitzar en futures peticions de recursos protegits.

Un altre avantatge important d’utilitzar OAuth és la capacitat de l’usuari d’anul·lar l’accés del client en qualsevol moment. Si l’usuari decideix que, per qualsevol motiu, ja no vol que el client pugui accedir als recursos protegits en nom seu, simplement acudeix a una interfície que heu creat i cancel·larà l’accés del client.

Comença aviat

Una de les coses més importants que podeu fer perquè la vostra API sigui un èxit és començar d'hora. Quan escriviu aquesta funció per crear una entrada a la base de dades, aneu endavant i trigueu el temps addicional i escriviu una interfície API.

Escriure una bona documentació

Res no mata una API més ràpid que no tenir una bona documentació. Tot i que alguns desenvolupadors poden adoptar una API poc documentada i esbrinar com se suposa que funciona, la majoria no voldrà.

Heu de documentar totes les trucades de l'API que tingueu disponibles i categoritzar les trucades de l'API segons el tipus de dades amb què actuïn. Juntament amb la documentació dels punts finals per a les trucades de l'API, heu de definir sistemàticament els arguments d'entrada necessaris i opcionals, així com les estructures de dades de sortida. Els arguments d’entrada haurien d’enumerar un valor predeterminat si n’hi ha, i també indicar el format de dades esperat com ara un número o cadena. Finalment, totes les trucades a l'API han de tenir una llista de les condicions d'error i els codis d'estat.

Per completar la documentació, assegureu-vos d’incloure un o dos exemples per a escenaris d’entrada i sortida comuns per a cada trucada API.

Desenvolupament API: Keep Simple

Si bé pot semblar que el desenvolupament d'una API és un esforç complicat, la idea d'una API en si mateixa no és un concepte nou i hi ha una gran quantitat de documentació disponible sobre cada tema que hem tractat aquí. Només heu d'assegurar-vos que utilitzeu bones pràctiques on els pugueu trobar i que proporcioneu una interfície consistent i ben documentada.