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 Вътрешна грешка в сървъра - Проблем от страна на сървъра, проверка на състоянието на сайта и/или докладване на проблем.

За повече информация относно HTTP кодовете на състоянието вижте спецификацията.

Предоставяйте пълни версии на ресурси, когато е възможно

Върнете пълното представяне на ресурса (т.е. обект с всички атрибути) на вашите потребители на API във всички отговори, където е възможно. Винаги предоставяйте пълната версия на ресурса в отговорите на заявки с кодове на състоянието 200 и 201, включително заявки PUT, PATCH и DELETE.

Отговорите на заявки със статус код 202 не трябва да съдържат всички полета на обекта

Вашият API трябва да приема сериализиран JSON в тялото на заявката

Вашият API трябва да предоставя възможност за предаване на сериализиран JSON в тялото на заявките PUT/PATCH/POST вместо или в допълнение към подадените данни от формуляра. Това създава симетрия в JSON отговорите:

Бъдете последователни при конструирането на пътища на ресурси

Имена на ресурси

Опитайте се да проектирате такива крайни URL адреси, които не изискват допълнителни действия за отделни ресурси. Когато е необходимо, добавете компонент "действие" към общия път, за да дефинирате ясно тези действия:

Използвайте малки имена на компоненти и атрибути на пътя

Използвайте малки букви за имената на компонентите на пътя на ресурса и ги разделете с тире.

По-добре е имената на атрибутите да се пишат с малки букви и е по-добре да се използва долна черта като разделител - по този начин имената на полетата могат да бъдат написани без скоби в Javascript:

Вашият API трябва да поддържа достъп до ресурс не само чрез неговия идентификатор

В някои случаи е неудобно за крайните потребители да имат достъп до ресурс чрез неговия идентификатор. Например за потребителя е по-удобно да осъществи достъп до конкретно приложение Heroku, като използва името на приложението, а не неговия UUID. В такива случаи трябва да организирате достъп както по име, така и по идентификатор:

Намалете до минимум броя прикачени файлове в пътя за достъп до ресурса

В модели на данни с родителски връзки между обекти, пътищата за достъп до ресурси могат да бъдат силно вложени:

Можете да ограничите дълбочината на влагане, като поставите ресурси в основната директория. Влагането се използва най-добре за посочване на достъп до колекции от ресурси:

Предоставете UUID на заявените ресурси

Всеки ресурс трябва да има атрибут id по подразбиране. Опитайте се винаги да използвате UUID като стойности на идентификатора на ресурса. Не използвайте идентификатори, които няма да бъдат уникални за вашата услуга, особено автоматично увеличаващи се идентификатори.
Изведете ресурса UUID във формат 8-4-4-4-12:

Предоставете информация за датата, на която ресурсът е създаден и модифициран

По подразбиране ресурсът трябва да съхранява информация за датата на създаването му created_at и да актуализира updated_at .

Временните стойности трябва да бъдат форматирани съгласно ISO8601

Връзките с външни обекти трябва да бъдат преместени в вложен обект

Външните връзки трябва да бъдат сериализирани като вложен обект:

Не като обектно поле:

Този подход ви позволява да добавите повече информация за свързания обект, без да се налага да променяте структурата на отговора:

Създавайте структурирани отговори при възникване на грешки

Осигурете последователно, структурирано тяло за отговор, когато възникнат грешки. В този случай отговорът трябва да съдържа четимо съобщение за грешка и по желание url, който показва на клиента къде да получи повече информация за проблема и как да го реши.

Покажете ограничение на броя заявки

Въвежда се ограничение на броя на заявките, за да се поддържа работоспособността на системата и възможността да се предоставя качествена услуга на други клиенти. Можете да използвате текущия алгоритъм за сегментиране, за да изчислите ограничението на броя на заявките. Върнете останалия брой заявки за всяка заявка в заглавката за отговор RateLimit-Remaining .

JSON във всички отговори трябва да бъде минимизиран

Допълнителното празно пространство увеличава размера на отговора и много клиенти на Javascript автоматично ще форматират JSON за четливост. Ето защо е по-добре да намалите JSON отговорите:

По желание можете да добавите способността да получавате по-подробен отговор, като посочите допълнителен параметър (например? Pretty = true) или зададете стойности за заглавката Accept (Accept: application/vnd.heroku + json; version = 3; отстъп = 4;).

Осигурете лесна за работа JSON схема

Предоставете JSON схема, за да опишете точно вашия API. Използвайте prmd, за да управлявате схемата, също така се уверете, че тя е валидирана с командата prmd verify .

Осигурете четлива документация

За да могат разработчиците да разберат как работи вашият API, предоставете им удобна документация. Ако сте създали JSON схема с помощта на prmd, както е описано по-горе, можете лесно да генерирате документация за Markdown за всички крайни URL адреси, като използвате командата prmd doc .

В допълнение към описанието на крайните URL адреси, предоставете преглед на API, включително следната информация:

  • процес на удостоверяване - получаване и използване на персонализиран маркер;
  • API стабилност и версия, както и информация за това как да изберете необходимата версия на API;
  • общи заглавки на заявки и отговори;
  • формат на грешка;
  • примери за използване на API с клиенти на различни езици;

Предоставете примерни заявки, които можете да тествате

Предоставете примерни заявки, които потребителите могат да тестват. За да тества тези заявки, потребителят трябва да извърши минимум действия:

Ако използвате prmd за генериране на документация, тогава такива примери ще бъдат генерирани автоматично за всеки краен URL адрес.

Опишете стабилността на вашия API

Можете да опишете степента на стабилност на вашия API или отделни крайни URL адреси, като зададете флагове за прототип/разработка/производство .

За повече информация можете да се обърнете към документа на Политиката за съвместимост на API за Heroku.

След като декларирате своя API за готовност и стабилност, не трябва да правите никакви модификации, които нарушават обратната съвместимост в рамките на тази версия. За да направите такива промени, създайте нов API клон с нов индекс на версията.