Content
- Fes els deures
- Sigui coherent
- Utilitzeu OAuth
- Comença aviat
- Escriure una bona documentació
- Desenvolupament API: Keep Simple
Emportar:
Els desenvolupadors de programari volen una forma d’integrar el seu programari amb el vostre, i no volen que s’hi desglossin coses. Aquí és on entra una API.
É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). En aquest article, 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 tanca 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 s’han de nomenar de manera coherent i haurien de tenir sentit en la connexió de la trucada d’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
És una pràctica habitual incloure una mena d’indicador d’estat en les dades de sortida que retorneu 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, fer que el client reculli les credencials d’usuari al 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 s’iniciï la sessió al vostre lloc, es torni a dirigir al client on rebrà un token d’accés per utilitzar en futures sol·licituds a recursos protegits.
Un altre avantatge important d’utilitzar OAuth és la capacitat de l’usuari de cancel·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 el seu funcionament, la majoria no volen.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.