HTTP Ръководство за изграждане на API

Това ръководство съдържа насоки за проектиране на HTTP API, които са извлечени от API на облачната платформа Heroku, а също така съдържа информация за нова функционалност и вътрешни API в Heroku.

Основните ни цели при изграждането на API са последователност и фокус върху внедряването на бизнес логика. Търсим различни, не непременно най-добрите, но добре документирани начини за разработване на API.

Тази статия предполага, че сте запознати с основните принципи на HTTP и JSON.

Принципът на разделение на отговорността

Когато проектирате, опитайте се да улесните системата, като разделите отговорността между различните части на цикъла на заявка-отговор. В същото време простотата на взетите решения ще ни позволи да се концентрираме върху решаването на все по-сложни проблеми. Исканията и отговорите се извършват, за да се получи достъп до определен ресурс или набор от ресурси. За да дефинирате обекта, който да получите, използвайте пътя на отговора и тялото за предаване на съдържание и заглавките за предаване на метаданни. Можете да предадете всички параметри в тялото на заявката, но, както показва практиката, това решение е по-малко гъвкаво. По-правилен подход би бил предаването на част от параметрите в хедърите.

Изисквайте използването на защитени връзки

Използвайте само защитени TLS връзки за извличане на данни с помощта на API.
По-добро решение би било да се отхвърлят всички заявки, които не използват TLS, а именно заявки през http или на порт 80, за да се избегне несигурен обмен на данни. В случаите, когато това не е възможно, отговорете с 403 Забранен отговор .

Пренасочванията се обезкуражават, тъй като позволяват неправилно поведение на клиента, без да се предоставят ясни обяснения. Клиентите, които разчитат на пренасочвания, удвояват по този начин сървърния трафик и използването на TLS в този случай е безполезно, тъй като важните данни са незащитени при първото обаждане.

Изисквайте версията в заглавката Accept

Наличието на множество версии и преминаването между тях може да бъде един от най-трудните аспекти при проектирането и използването на API. Ето защо е по-добре да вземете този момент предвид предварително.

За да попречите на клиента да използва нестабилен API, най-добре е да проверите за неговата версия във всяка заявка. Трябва обаче да избягвате да указвате версията по подразбиране, тъй като това значително усложнява заглавието и тази версия може също да се промени в бъдеще.

Най-добре е да добавите версията в заглавката заедно с други метаданни, като използвате заглавката Accept с персонализиран тип съдържание:

Използвайте ETags Header за кеширане

Включете заглавката ETags във всички заявки, като посочите версията на върнатия ресурс. Това ще позволи на потребителите да кешират ресурси и да прилагат условни заявки, като използват заглавката If-None-Match, за да определят дали кешът трябва да се актуализира или не.

Използвайте Request-ID за самоанализ

Включете заглавката Request-Id, съдържаща стойността на UUID във всеки отговор на сървъра. Като регистрирате тези стойности в клиента, сървъра или друга услуга, можете да отстранявате грешки и да диагностицирате проблеми с заявките.

Разделете големите отговори на сървъра на по-малки, като използвате заглавката Range

Големите отговори трябва да бъдат разделени на по-малки, като се използва заглавката Range. За повече информация относно заглавките на заявките/отговорите, кодовете на състоянието и ограниченията вижте дискусията за използване на API на платформата Heroku. .

Върнете подходящи кодове за състояние

Върнете съответния HTTP код на състоянието във всеки отговор. Успешните отговори трябва да съдържат следните кодове на състоянието:

200 - GET заявката е завършена успешно, синхронната DELETE или PATCH заявка е завършена успешно или синхронната PUT заявка актуализира съществуващ ресурс.
201 - Завършена синхронна POST заявка, синхронната PUT заявка създаде нов ресурс.
202 - Получена е заявка за POST, PUT, DELETE или PATCH, която ще бъде обработена асинхронно.
206 - GET заявката е успешна, но ще бъде върнат частичен отговор (вижте раздела в заглавката Range).

Върнете съответните кодове за грешки, за да предоставите повече информация за причините за тях:

422 Unprocessable Entity - Вашето искане е разпознато, но съдържа невалидни параметри.
429 Твърде много заявки - Лимитът на заявките е надвишен, моля, опитайте по-късно.
500 Вътрешна грешка в сървъра - Проблем от страна на сървъра, проверка на състоянието на сайта и/или докладване на проблем.