Сега, нека ред.
REST (представителна държавна Transfer - представителна държавна Transfer).
REST (представителна държавна Transfer - представителна държавна Transfer).
Структурата на останалите API
1. архитектура клиент-сървър
2. Без гражданство сървъра
4. многослойна структура
5. единния интерфейс
- идентифициране на ресурси
- Взаимодействие с ресурси чрез представяне
- самостоятелни публикации
- Хипермедия приложения като механизъм държавния контрол (HATEOAS)
6. Кодът на заявка (по желание)
Сега за всеки елемент в детайли.
Архитектура, клиент - сървър. Разделянето на логиката на приложението на различни клиенти, да си код по-преносим и сървър структура прости и по-мащабируема. Развитието на клиента и сървъра може да се извършва напълно независимо.
Без гражданство - сървър. статус на клиента не се съхранява на сървъра по някакъв начин, той се занимава изключително с клиента. Това улеснява изграждането и поддръжката на сървъра, което го прави по-стабилна.
С възможност за кеширане. ясни система кеш заявки до сървъра, за да бъдат разработени, че може значително да подобри производителността.
Многопластова структура. Наличие / липса на междинни сървъри, кеширане, балансиране на натоварването, допълнителна прокси трябва да остане напълно незабелязано от страна на клиента.
идентификация на ресурсите. Всеки ресурс има уникален URI (Uniform Resource Identifier - Uniform Resource Identifier). Например:
Що се отнася до идентификационния номер, аз съветвам да се търси в посока на UUID (универсално уникален идентификатор), тя поддържа повечето от базата данни, и този подход ще помогне да се гарантира, krosc-система на уникални идентификатори. например:
Самостоятелно съдържа публикации. Всеки отговор трябва да съдържа цялата необходима информация, за да можете да се справят както трябва, без да се прибягва до помощта на други ресурси.
HATEOAS. Хипермедията двигателя на Заявление-членка.
Хипермедията механизъм за контрол на условията за кандидатстване.
Хипермедия - тип ресурс на съдържание с възможност за маркиране на хипертекст. Hypertext, в този контекст, тъй като той смята, Филдинг е едновременното представяне на информация и изберете елементи.
"По този начин, хипермедия е просто разширение, което се характеризира с наличието на информационното съдържание на временните връзки към друго съдържание в рамките на медийния поток".
по искане на кода. Като опция се предлага елемент от структурата. Тя ви позволява да получите код за последващо изпълнение на клиента.
По този начин, ако кандидатурата ви отговаря на всички изисквания (ограничения), както е описано по-горе, той може спокойно да се нарече RESTful. Изключение е само кода на искането - този параметър не е задължително.
Един добър API е лесен за разбиране и лесни за прилагане.
Основи ПОЧИВКА през HTTP.
Ресурс - уникален обект, достъпна чрез уникален URL адрес.
Главна URL трябва да бъде разбираема, без документация.
това ще ви помогне да се опрости поддръжката на API за в бъдеще. Един добър вариант би могъл да бъде име на домейн префикс:
Има 2 основни вида на ресурсите в областта на архитектурата REST: събиране и събиране елемент.
Колекция е съвкупност от независими и самостоятелни елементи.
Пример за връзка към събиране на потребители:
Потребителите Element за събиране, или конкретен потребител, в този случай, могат да бъдат представени като:
Съществителните - добре, глаголи - лошо.
колекции от имена трябва да бъдат от съществено значение (множествено число съществителни), и те трябва да са най-конкретен и ясен (самостоятелно документиране). Когато става въпрос за кучета, той трябва да е куче, а не само животни.
Всеки ресурс в RESTful API управлява по-определени минималните задължителни глаголи. За повечето случаи е достатъчно 4 главния глагол (HTTP метод):
GET, PUT, DELETE - idempotent.
Idempotency означава, че без значение колко пъти ние не се обади на този метод - резултатът ще бъде един и същ.
Събиране на потребителски машини:
(HTTP Status Code), следва да се направи разграничение две основни семейства на кода на състоянието:
4xx - проблем възниква от страна на потребителя и той може да го оправи, нали, като въведете необходимата информация за искането.
5xx - проблемът е възникнал на сървъра и неговото решение, потребителят може да изпрати искане до службата за поддръжка.
Грешките трябва да бъдат ясно описани, не само потребителят знае какво трябва да направи, но също така и лесен за навигация, ако потребител ви изпраща заявка за решаване на проблема.
Пример добре написан отговор на грешката:
HTTP статус код: 401
Не забравяйте! Можете да напишете API за развитието на такива като теб.
Използвайте минимум необходимия код в състоянието на приложението.
Понякога може да е достатъчно, за 3:
2. 400 Bad Request (невалидна заявка)
3. 500 Вътрешна грешка в сървъра (Вътрешна грешка в сървъра)
Ако не е достатъчно, допълнени, при необходимост:
1. 201 Created (създаден успешно)
2. 304 Not Modified (данните не се е променило)
3. 404 Not Found (не е намерен)
5. 403 Forbidden (достъпът е отказан)
Опитайте се да се направи оценка на ползите от всеки елемент, който да добавите към потребителя. Не забравяйте, че голям брой, особено на ненужни елементи, може да обърка дори опитни предприемачи.
В някои случаи е полезно да има настройка, за да потисне код на състоянието грешка, че клиентът би винаги, когато е необходимо, за да получите кода, 200, например.
Тя не е на мястото си, за да добавите гъвкавост, за да си API.
Версиите.
Не забравяйте да включите номера на версията, дори и ако не искате да промените интерфейса - всичко може да се промени бързо.
или параметри на заявката:
Няма причина да се направи дългата версия на заглавието, като ги поставите в точка: v1.03
Page-въпрос.
Всяка колекция, без значение колко малки, по ваше мнение, тя не е била да се даде на една страница. Взема решение за формата на издаването на сборника, например, Content-Type: заявление / JSON, «виртуална памет":> Опитайте се да се използва винаги един и същ формат за всички отговори за кандидатстване - за улесняване на живота и себе си и разработчиците клиентския софтуер.
Ако изберете някои defolnnye стойности за «граница» параметри, «компенсира», и е вероятно да се ограничи максималната стойност за «граница».
Скриване на други сложни елементи на искането за "?".
Ако искането ви GET е необходимо да се използват различни филтри - ги поставя зад въпросителния знак (в параметъра URL):
Дава на потребителя само това, което той иска.
Нека само тези области, за да получите на клиента да поиска той се нуждае от:
Форматът на данните, за да се даде.
Не се ограничавайте и да е формат. Направете избор номер, например, JSON и XML. В този лесен начин вие може значително да опрости развитието на клиентите, и вече няма да се наложи да изберете нещо, един. завърна формат на данните може да бъде описан като в заглавията на HTTP и заявка низ:
И не забравяйте да изберете някои формат по подразбиране.
Това е един от малкото видове ресурси, които се обречени да останат глагол. Искам да кажа, глобалното търсене.
Отново, различни филтри могат да се използват в зависимост от системата, използвана от търсачката.
Някои локално търсене в рамките на една колекция, можете да направите и обикновен филтър:
Използвайте, когато е възможно, най-новата версия на OAuth - OAuth 2.0 - Тази система е най-известните дизайнери, и работи добре. Защо изобрети колелото?
Документация.
Това е един от най-важните аспекти на един добър API. Всеки, който се е сблъсквал с писане от страна на клиента скриптове, ще се съгласите с мен. Часове, прекарани на добра документация, ще бъдат компенсирани от дълги месеци работа подкрепа. Номерът е проста - да се опише кратко и ясно всички получени данни и да се даде, както и назначаването на методи. Не забравяйте! Пишеш за програмисти. Не е необходимо да се опишат някои очевидни точки. Донесете всичко, за да се даде статут на кодовете; списък на всички получени параметри ги описват, когато е необходимо; да съдържа връзки към по-подробна материал; примери за данни, както е подходящо, с тяхното описание.
Опитайте се да дадете отговори в препратка към всички свързани с ресурсите, ако искате да се съобразяват с принципа HATEOAS, и призова RESTful. За това ще ви бъде много любители на разработчиците на клиентските програми - те не се налага да генерирате тези връзки.
Сега най-важното нещо!
Фасада модел за API.
Всяко развитие API трябва да започва с подробно изследване на интерфейса. В действителност, в началото на писане код на ръцете трябва да бъде цялото си URI API с подробна документация за всички параметри на всяка налична за даден метод URI, с всички кодове за връщане на състоянието и формат на данните, за да се върнат. В идеалния случай, този интерфейс вече не трябва да се променя в хода на по-нататъшното развитие. Този подход значително улеснява и ускорява работата по основния код API, и позволява паралелно писане клиентски софтуер вече е в началните етапи на развитие.
Не забравяйте! Този интерфейс трябва да бъде просто и ясно, че единственият начин да се постигне щастие и хармония.
Старши Web Developer / Екип олово, Company SECL Група / продажби по интернет технологии
Свързани статии