Что такое программный интерфейс или api?

Содержание:

Краткое введение в RAML
Возможности API MCN Telecom
На что способны API?
Картинки с котами, собаками и лисами
- Картинки котиков
- Картинки собачек
- Картинки лисичек
API2:2019 — Broken User Authentication (Недостатки аутентификации пользователей)
Четыре типа параметров
Форматируем JSON и используем подсветку синтаксиса кода
Отсутствие результата — тоже результат
Что такое API?
Ещё несколько примеров API
Множественные примеры запросов
Примеры описания ресурсов
Тестовые потоки
Endpoint
Примеры параметров
API как соглашение — сначала проверьте спецификацию!
API везде!
Тестирование API без документации
- Сканирование портов
- Перебор запросов
Плюсы и минусы работы с API
Заключение

Краткое введение в RAML

Вводная часть

версия RAML;
имя документа;
URI, по которому доступен API;
версия API, описываемая в документации.

#% RAML 0.8
title: Example API
baseUri: http://api.example.com/{version}
version: v1

protocols:

documentation
    - title: Home
        content: |
                  API Test Documentation

Схемы безопасности

#%RAML 0.8
title: Example API
version: 1
baseUri: https://api.example.com/{version}
securedBy: 
securitySchemes:
    - oauth_2_0:
               type: OAuth 2.0
        describedBy:
            headers:
                Authorization:
                         type: string
            queryParameters:
                access_token:
                      type: string
            responses:
                401:
                    description: |
                        Bad or expired token.                 
                 403:
                    description: |
                        Bad OAuth request 
        settings:
          authorizationUri:  https://example.com/oauth/authorize         
          accessTokenUri: https://example.com/oauth/token
          authorizationGrants:

в параметре type указывается, что в API используется авторизация по протоколу OAuth2;
далее указывается, что авторизационные данные можно передавать либо в заголовке Authorization, либо в query-параметре access_token;
после этого следуют возможные коды ответов и их описания;
в конце раздела, в секции settings указываются URL для авторизации, URL для получения токена, а также необходимые для аутентификации параметры (authorization grants).

#%RAML 0.8
title: Example API
version: 1
baseUri: https://api.example.com/{version}
securedBy: 
securitySchemes:
    - oauth_2_0: !include oauth_2_0.yml

Объекты и методы

/document
 get:
 put:
 post:
  /{documentId}
   get:
   delete:

/documents
   get
     headers:
        X-Auth-Token:
        required: true

/document
      /{documentId}
              uriParameters:
                       id:
                        description: document identification number
                        type: string
                        pattern: ^{2}\-{3}\-\d{2}\-\d{5}$

/documents
   get:
        description: Retrieve a list of documents
   post:
         description: Add a new document
   body: 
          application/x-www-form-urlencoded
                 formParameters:  
                         id: 
                           description: document identification number
                           type: string
                           pattern: {2}\-{3}\-\d{2}\-\d{5}$
                         name:
                             description: the name of the document
                             type: string
                             required: true
                          author: 
                                description: The name of the author
                                type: string
                                 required: true

/documents
  get

Query-параметры

 /document:
     get:
       queryParameters:
         author:
           displayName: Author
           type: string
           description: The author's full name
           example: Ivan Petrov
           required: false
         name:
           displayName: Document Name
           type: string
           description: The name of the document
           example: Delivery contract
           required: false
         signingDate:
           displayName: signingDate
           type: date 
           description: The date when the document was signed
           example: 2015-07-15
           required: false

Профили

#% RAML 0.8
title: Example API
baseUri: http://api.example.com/{version}
version: v1

traits:
 - searchable:
    queryParameters:
         author:
           displayName: Author
           type: string
           description: The author's full name
           example: Ivan Petrov
           required: false
         name:
           displayName: Document Name
           type: string
           description: The name of the document
           example: Delivery contract
           required: false
         signingDate:
           displayName: signingDate
           type: date 
           description: The date when the document was signed
           example: 2015-07-15
           required: false

/document:
     get:
            is:

Описание ответа

 /documents:
   /{documentId}:
     get:
       description: Retrieve document information
       responses:
         200:
          body:
           application/json:
             schema |
               {"$schema": “http://json-schema.org/schema”,
                "type":"object"
                "description": "a document"
                "properties": {
                     "id":{"type":"string"}
                     "name":{"type":"string"}
                     "author":{"type":"string"}
                     "signingDate": {"type":"date"}
               example: |
               {"data:" {
                  "id": "DOC3456"
                  "name": "New Delivery Contract"
                  "author": "Ivan Petrov"
                  "signingDate": "2015-05-20"
                },
                "success": true
                "status": 200
              }

schemas:
 - !include document-schema.yaml

/articles:
 get:
  responses:
   200:
    body:
     application/json:
      schema: document

Возможности API MCN Telecom

Возможности API MCN Telecom, в частности, включают:

Управление функциями ВАТС и телефонии через API (и в т. ч. с использованием WebHooks) может включать такие действия, как:

уведомление о входящем звонке;
выполнение исходящего вызова;
получение записей звонков;
предоставление детальной статистики по входящим и исходящим вызовам;
получение списка свободных телефонных номеров заданного региона;
резервирование городских номеров;
подключение телефонных номеров на выбранный тариф

и многое другое.

Интеграция ВАТС с CRM позволяет:

поднимать карточку звонящего клиента при входящем звонке;
совершать исходящие вызовы из CRM;
прикреплять записи разговоров к карточкам клиентов в CRM-системе;
построить воронку продаж, проанализировав в едином приложении данные по звонкам и продажам;
автоматически направлять звонки клиентов на персонального менеджера с поднятием карточки в CRM;
синхронизировать телефонный справочник сотрудников компании с внутренними номерами в виртуальной АТС и CRM-системе.

Как воспользоваться API MCN Telecom

API MCN Telecom постоянно расширяется, дополняется новыми методами, наиболее часто запрашиваемыми нашими клиентами. При выпуске новых версий API прежние остаются доступными для использования.

Чтобы воспользоваться API, нужно произвести настройки в Личном кабинете в разделе API, а также во внешней системе (использующей API MCN Telecom).

Для авторизации при обращении по API используется секретный ключ (токен), который должен быть предварительно сгенерирован и далее записан в использующей системе, где необходимо.

Документация API с подробным описанием методов доступна в Личном кабинете.

На что способны API?

Широкое разнообразие API в современных браузерах позволяет наделить ваше приложение большими возможностями. Достаточно посмотреть список на странице MDN APIs index page.

В частности, к наиболее часто используемым категориям API (и которые мы рассмотрим далее в этом модуле) относятся :

API для работы с документами, загруженными в браузер. Явный пример — DOM (Document Object Model) API, позволяющий работать с HTML и CSS — создавать, удалять и изменять HTML, динамически изменять вид страницы и т.д. Любое всплывающее окно на странице или появляющееся «на ходу» содержимое — всё это благодаря DOM. Узнайте больше об этой категории API на странице Работа с документами.
API, принимающие данные от сервера, часто используются, чтобы обновить небольшие части веб-страницы. Эта, казалось бы, малая деталь оказывает огромное влияние на производительность и поведение сайтов, так как нет необходимости перезагружать всю страницу целиком, если вам нужно просто обновить список товаров или новых доступных историй. Это также сделает приложение или сайт более отзывчивым и «живым». Список API, благодаря которым это возможно, включает: и Fetch API. Вы также могли встретить термин Ajax, описывающий эту технологию. Узнать больше об этой категории API на странице Получение данных от сервера.
API для работы с графикой широко поддерживаются браузерами, самые популярные: Canvas и WebGL, позволяющие программно изменять данные о пикселях, содержащиеся в элементе HTML для создания 2D и 3D изображений. Например, вы можете нарисовать фигуры, скажем, прямоугольники или круги, импортировать изображение в canvas и применить к нему фильтры, такие как сепия или оттенки серого с помощью Canvas API, или создать сложное 3D-изображение с освещением и текстурами, используя WebGL. Такие API часто используют в сочетании с API создания анимационных циклов (таких как ) и другими для создания постоянно меняющегося изображения на экране, как в мультфильмах или играх .
Аудио и Видео API как , Web Audio API, и WebRTC позволяют делать действительно интересные вещи с мультимедиа. Например, создать собственный пользовательский интерфейс (User Interface, UI) для проигрывания аудио/видео, вывод на экран субтитров, записывать видео с веб-камеры для обработки в canvas (см. выше) или для передачи на другой компьютер в видео-конференции, применять звуковые эффекты к аудио-файлам (такие как gain, distortion, panning и т.д.).
API устройств — в основном, API для обработки и считывания данных с современных устройств удобным для работы веб-приложений образом. Мы уже говорили об API Геолокации, позволяющем считать данные о местоположении устройства. Другие примеры включают уведомление пользователя о появившемся обновлении для веб-приложения с помощью системных уведомлений (см. Notifications API) или вибрации (см. Vibration API).
API хранения данных на стороне пользователя приобретают всё большее распространение в веб-браузерах — возможность хранить информацию на стороне клиента очень полезна, когда необходимо создать приложение, которое будет сохранять своё состояние между перезагрузками страницы, или даже работать, когда устройство не в сети. В данный момент доступно немало таких API. Например, простое хранилище данных в формате имя/значение (name/value) Web Storage API или хранилище данных в формате таблиц IndexedDB API.

Существует множество сторонних API; некоторые из наиболее популярных, которые вы рано или поздно будете использовать, включают:

Twitter API для добавления такой функциональности, как показ последних твитов на сайте.
Google Maps API для работы с картами на веб-странице (интересно, что Google Maps также использует этот API). Теперь это целый набор API, который может справляться с широким спектром задач, как свидетельствует Google Maps API Picker.
Набор Facebook API позволяет использовать различные части платформы Facebook в вашем приложении, предоставляя, например, возможность входа в систему с логином Facebook, оплаты покупок в приложении, демонстрация целевой рекламы и т.д.
YouTube API, предоставляющий возможность встраивать видео с YouTube на вашем сайте, производить поиск, создавать плейлисты и т.д.
Twilio API — фреймворк для встраивания функциональности голосовой и видео связи в вашем приложении, отправки SMS/MMS из приложения и т.д.

Note: вы можете найти информацию о гораздо большем количестве сторонних API в Каталоге Web API.

Картинки с котами, собаками и лисами

Страница будет выглядеть каждый раз по-новому, если в её верхнюю часть поместить картинку, которая будет меняться при каждом новом посещении страницы.

Картинки котиков

— возвращается только ссылка на картинку или гифку. Ссылки случайные и ведут на сторонние сервера.

Каждая картинка из базы имеет номер, но API не даёт номер, а получить картинку по номеру только открыв сайт и достать картинку из исходного текста страницы. Совсем простенький скрипт для этого (для более быстрого исполнения я не использую re):

Картинки собачек

— возвращает размер картинки (или gif или видео) в байтах и ссылку на неё. Все ссылки выглядят как

Другие варианты запросов:

— получить название какой-нибудь случайной картинки (случайная строка)
— названия всех картинок
— предложить свою картинку.

Картинки лисичек

— возвращает 2 варианта ссылки на картинку. Пути к картинкам выглядят так: , где id — число от 1 до 121. Также все картинки есть в репозитории: . Это позволяет вручную выбрать интересные картинки и использовать только их.

API2:2019 — Broken User Authentication (Недостатки аутентификации пользователей)

OAuth 2.0, OpenID Connect, WebAuthn

Пользователь заходит на сайт и нажимает кнопку «Зайти с помощью Google аккаунта»
Сервер посылает запрос на Google.
Google показывает пользователю свою форму логина.
Пользователь вводит логин/пароль.
Google проверяет логин/пароль и отправляет на наш сервер приложений access token и refresh token.
Для аутентификации сервер расшифровывает token или получает информацию о пользователе по Google API.
После этого при каждом запросе к серверу клиент будет передавать access token в запросе, а наш сервер проверять его на валидность в Google и только после этого передавать запрошенные данные.
При окончании срока действия access токена сервер использует refresh токен для получения нового.

Какие плюсы Token-Based Authentication для сервера приложений:

Не надо хранить пароли в базе данных на сервере, таким образом сразу избавляемся от уязвимости Insecure Passwords.
В некоторых случаях можно вообще избавиться от базы данных на сервере и получать всю необходимую информацию из Google или других систем.
Нет проблем с безопасностью, характерных для остальных методов:

При компрометации логина/пароля доступ к данным получается сразу и длится пока пользователь сам не заметит факт взлома, у токенов же есть время жизни, которое может быть небольшим.
Токен автоматически не уйдет на сторонний сайт, как Cookie.
Cookie-Based Authentication подвержена атаке Cross-Site Request Forgeries (CSRF) и, соответственно, необходимо использовать дополнительные механизмы защиты.
Можно не хранить сессию пользователя на сервере, а токен проверять каждый раз в Google.

Минус видится один:

Четыре типа параметров

REST API обладают 4 типами параметров:

Параметры заголовка: параметры, включенные в заголовок запроса, обычно относятся к авторизации.
Параметры path: Параметры в пределах path конечной точки перед строкой запроса, отделяются знаком . Обычно эти параметры выделяются фигурными скобками.
Параметры строки запроса: Параметры в строке запроса конечной точки, располагаются после знака .
Параметры тела запроса: Параметры, включенные в тело запроса. Обычно в формате JSON.

Tip: Термины для каждого из этих типов параметров взяты из спецификации OpenAPI, которая определяет формальную спецификацию, которая включает описания каждого типа параметра (см. Шаг 4 Объект ). Использование терминологии промышленного стандарта поможет разработать словарь элементов API для их описания.

Форматируем JSON и используем подсветку синтаксиса кода

Используйте правильный формат JSON для ответа. Такие инструменты, как JSON Formatter and Validator, помогут скорректировать синтаксис.

Если есть возможность добавить подсветку синтаксиса, обязательно нужно делать это. При использовании статического генератора сайтов, например Jekyll или синтаксис Markdown с GitHub, можно использовать встроенную подсветку синтаксиса Rouge. Другие статические генераторы сайтов могут использовать Pygments или аналогичные расширения.

Rouge и Pygments полагаются на «лексеры», чтобы указать, как код должен быть выделен. Например, некоторыми распространенными лексерами являются , , , , , и .

Отсутствие результата — тоже результат

Если сервер корректно обработал вопрос и никакой внештатной ситуации не возникло — следовательно, это не ошибка. К сожалению, весьма распространён антипаттерн, когда отсутствие результата считается ошибкой.

Плохо

Статусы означают, что клиент допустил ошибку; однако в данном случае никакой ошибки сделано не было, ни пользователем, ни разработчиком: клиент же не может знать заранее, готовят здесь лунго или нет.

Хорошо:

Это правило вообще можно упростить до следующего: если результатом операции является массив данных, то пустота этого массива — не ошибка, а штатный ответ. (Если, конечно, он допустим по смыслу; пустой массив координат, например, является ошибкой.)

Что такое API?

Для JavaScript на стороне клиента, в частности, существует множество API. Они не являются частью языка, а построены с помощью встроенных функций JavaScript для того, чтобы увеличить ваши возможности при написании кода. Их можно разделить на две категории:

API браузера встроены в веб-браузер и способны использовать данные браузера и компьютерной среды для осуществления более сложных действий с этими данными. К примеру, API Геолокации (Geolocation API) предоставляет простые в использовании конструкции JavaScript для работы с данными местоположения, так что вы сможете, допустим, отметить своё расположение на карте Google Map. На самом деле, в браузере выполняется сложный низкоуровневый код (например, на C++) для подключения к устройству GPS (или любому другому устройству геолокации), получения данных и передачи их браузеру для обработки вашей программой, но, как было сказано выше, эти детали скрыты благодаря API.
Сторонние API не встроены в браузер по умолчанию. Такие API и информацию о них обычно необходимо искать в интернете. Например, Twitter API позволяет размещать последние твиты (tweets) на вашем веб-сайте. В данном API определён набор конструкций, осуществляющих запросы к сервисам Twitter и возвращающих определённые данные.

Итак, выше мы поговорили о том, что такое JavaScript API клиентской части и как они связаны с языком JavaScript. Давайте теперь тезисно запишем основные понятия и определим назначение других инструментов JavaScript:

JavaScript — Язык программирования сценариев высокого уровня, встроенный в браузер, позволяющий создавать функциональность веб-страниц/приложений. Отметим, что JavaScript также доступен на других программных платформах, таких как Node. Но пока не будем останавливаться на этом.
API браузера (Browser APIs) — конструкции, встроенные в браузер, построенные на основе языка JavaScript, предназначенные для облегчения разработки функциональности.
Сторонние API (Third party APIs) — конструкции, встроенные в сторонние платформы (такие как Twitter, Facebook) позволяющие вам использовать часть функциональности этих платформ в своих собственных веб-страницах/приложениях (например, показывать последние Твиты на вашей странице).
Библиотеки JavaScript — Обычно один или несколько файлов, содержащих . Такие файлы можно прикрепить к веб-странице, чтобы ускорить или предоставить инструменты для написания общего функциональности. Примеры: jQuery, Mootools и React.
JavaScript фреймворки (frameworks) — Следующий шаг в развитии разработки после библиотек. Фреймворки JavaScript (такие как Angular и Ember) стремятся к тому, чтобы быть набором HTML, CSS, JavaScript и других технологий, после установки которого можно «писать» веб-приложение с нуля. Главное различие между фреймворками и библиотеками — «Обратное направление управления» ( “Inversion of Control” ). Вызов метода из библиотеки происходит по требованию разработчика. При использовании фреймворка — наоборот, фреймворк производит вызов кода разработчика.

Ещё несколько примеров API

Слово «application» (прикладной, приложение) может применяться в разных значениях. В контексте API оно подразумевает:

фрагмент программного обеспечения с определённой функцией,
сервер целиком, приложение целиком или же просто отдельную часть приложения.

Любой фрагмент ПО, который можно чётко выделить из окружения, может заменять букву «А» в англоязычной аббревиатуре, и тоже может иметь некоторого рода API. Например, при внедрении в код разработчиком сторонней библиотеки, она становится частью всего приложения. Будучи самостоятельным фрагментом ПО, библиотека будет иметь некий API, который позволит ей взаимодействовать с остальным кодом приложения.

В объектно-ориентированном проектировании код представлен в виде совокупности объектов. В приложении таких объектов, взаимодействующих между собой, могут быть сотни. У каждого из них есть свой API — набор публичных свойств и методов для взаимодействия с другими объектами в приложении. Объекты могут также иметь частную, внутреннюю логику, которая скрыта от окружения и не является API.

Множественные примеры запросов

Если имеется много параметров, можно попробовать включить несколько примеров запросов. В API CityGrid Places конечная точка выглядит следующим образом:

Однако есть буквально , которые можно использовать с этой конечной точкой. В результате документация включает несколько примеров запросов, которые показывают различные комбинации параметров:

Добавление множественных примеров запросов имеет смысл, когда параметры обычно не используются вместе. Например, есть несколько случаев, когда можно фактически включить все 17 параметров в один и тот же запрос, поэтому любой пример будет ограничен в том, что он может показать.

В этом примере показано, как «Найти отели в Бостоне, просматривая результаты с 1 по 5 страницы в алфавитном порядке»:

Сколько разных запросов и ответов нужно показать? Вероятно, это не простой ответ, но, не более, чем несколько. Нам решать, что нужно для нашего API. Пользователи обычно вникнут в шаблон после нескольких примеров.

Примеры описания ресурсов

Вот пример описания проекта Mailchimp:

Как правило, API имеет несколько конечных точек, сгруппированных в одном ресурсе. В этом случае вы описываете как общий ресурс, так и отдельные конечные точки. Например, ресурс Campaigns имеет различные конечные точки, которые также описаны:

POST
GET
GET
PATCH
DELETE
POST
POST
POST
POST
POST
POST
POST
POST

А вот описание API ресурса Membership Object в проекте

Для ресурса “Membership” (или “Object”, как они его называют) существует 7 различных конечных точек или методов, которые вы можете вызвать. API Box описывает ресурс Membership и каждую из конечных точек, которые позволяют получить доступ к ресурсу.

Иногда общий ресурс не описан; вместо этого в нем просто сгруппированы конечные точки. Основная часть описания появляется в каждой конечной точке. Например, в API Eventbrite есть ресурс Events:

Хотя ресурс “Events” здесь не описан, описания добавлены для каждой конечной точки. Ресурс Events содержит все эти конечные точки:

и так далее…

Tip: Когда разработчики создают API-интерфейсы, у них возникает вопрос проектирования: использовать много вариантов конечных точек (как в API-интерфейсе Eventbrite) или предоставить множество параметров для настройки одной и той же конечной точки. но все же лучше найти баланс. Кажется, что тенденция заключается в предоставлении отдельных конечных точек, а не в предоставлении множества потенциально запутанных параметров для одной и той же конечной точке. С другой стороны, API-интерфейсы GraphQL (которые я не рассматриваю в этом курсе) предоставляют одну конечную точку различными способами запроса информации, содержащейся в конечной точке. См. Различия в GraphQL и REST, объясняемые на бургерах, для пояснения GraphQL и REST.

В качестве еще одного примера вот пример ресурса Relationship API Instagram

Ресурс не описан, но является контейнером для конечных точек этого ресурса. Описания добавлены для каждого из ресурсов, сгруппированных в ресурсе Relationships:

GET
GET
GET
GET
POST

и еще в качестве пример API с ресурсами и конечными точками, проверьте .

Tip: Скорее всего, описание ресурса мы будем использовать в разных местах — обзоры продуктов, учебные пособия, примеры кода, быстрые ссылки и т.д. В результате приложим немало усилий для его создания. Давайте подумаем о том, чтобы сохранить описание многократно используемого фрагмента в своем инструменте разработки, чтобы мы могли использовать его, не прибегая к копипасте в нашем кратком руководстве.

Тестовые потоки

Давайте разделим и обозначим три вида потоков тестирования, которые составляют наш план тестирования:

Изолированное тестирование запросов — выполнение одного запроса API и соответствующая проверка ответа. Такие базовые тесты — это минимальные строительные блоки, с которых мы должны начинать. И нет смысла продолжать тестирование, если эти тесты упадут.
Многоступенчатый рабочий поток с несколькими запросами — тестирование серии запросов, которые являются обычными действиями пользователя, поскольку одни запросы могут зависеть от других. Например, мы выполняем запрос POST, который создает ресурс и возвращает автоматически сгенерированный идентификатор в своем ответе. Затем мы используем этот идентификатор, чтобы проверить, присутствует ли этот ресурс в списке элементов, полученных запросом GET. Затем мы используем PATCH для обновления новых данных и снова вызываем запрос GET для проверки этого обновления. И в завершении, мы УДАЛЯЕМ этот ресурс и снова используем GET, чтобы убедиться, что записи больше нет.
Комбинированные тесты API и тесты веб-интерфейса — это в основном относится к ручному тестированию, при котором мы хотим обеспечить целостность данных и согласованность между пользовательским интерфейсом и API.

Мы выполняем запросы через API и проверяем действия через пользовательский интерфейс веб-приложения и наоборот. Цель этих потоков проверки целостности состоит в том, чтобы гарантировать, что, хотя на ресурсы влияют различные механизмы, система по-прежнему поддерживает ожидаемую целостность и согласованный поток данных.

Endpoint

Адрес, на который посылаются сообщения называется Endpoint.
Обычно это URL (например, название сайта) и порт. Если я хочу создать веб сервис
на порту 8080 Endpoint будет выглядеть так:

Если моему Web сервису нужно будет отвечать на различные сообщения я
создам сразу несколько URL (interfaces) по которым к сервису можно будет обратиться.
Например

Как видите у моих эндпойнтов (Enpoints) различные окончания. Такое окончание в Endpoint
называются Resource, а начало
Base URL.

Такое определение Endpoint и Resource используется, например, в

SOAP UI

для RESTful интерфейсов
https://andreyolegovich.ru:8080 — это Base URL
/resource1/status — это Resource

Endpoint = Base URL + Resource

Понятие Endpoint может использоваться в более широком смысле. Можно сказать, что
какой-то определённый роутер или компьютер является Endpoint. Например, в понятии
Endpoint Management под Endpoint
имеют в виду конечное устройство

Обычно это
понятно из контекста.

Также следует обратить внимание на то, что понятие Endpoint выходит за рамки
RESTful и может использовать как в SOAP так и в других протоколах.

Термин Resource также связан с RESTful, но в более широком смысле может
означать что-то другое.

Примеры параметров

Скриншот ниже является примером раздела параметров с Box API:

Пример параметра BOX API

В этом примере параметры сгруппированы по типу:

параметры path,
параметры запроса,
параметры тела.

Конечная точка также выделяет параметр path распознаваемым образом в определении конечной точки.

Часто параметры просто перечислены в таблице или списке определений, как в этом примере:

Параметр	Обязательно/Опционально	Тип данных
format	Optional	String

Вот пример документации API Yelp

Можно форматировать значения различными способами, кроме таблицы. При использовании списка определений или другого не табличного формата, обязательно нужно разработать стили, которые сделают значения легко читаемыми.

API как соглашение — сначала проверьте спецификацию!

API — это, по сути, соглашение между клиентом и сервером или между двумя приложениями

Перед тем, как начать любое тестирование функциональности, важно убедиться в правильности соглашения. Это можно сделать сначала проверив спецификацию (или само соглашение службы, например, интерфейс Swagger или ссылку OpenAPI) и убедившись, что:

эндпоинты правильно именованы;
ресурсы и их типы правильно отражают объектную модель;
нет отсутствующей или дублирующей функциональности;
отношения между ресурсами правильно отражаются в API.

Приведенные выше рекомендации применимы к любому API, но для простоты в этом посте мы предполагаем наиболее широко используемую архитектуру веб-API — REST через HTTP

Если ваш API спроектирован именно как RESTful API, важно убедиться, что контракт REST действителен, включая всю семантику, соглашения и принципы HTTP REST. (описание тут, тут, и здесь)

Если у вас общедоступный API, ориентированный на клиента, такое тестирование может быть вашим последним шансом убедиться, что все требования соглашения выполнены. После публикации и использования API любые внесенные вами изменения могут внести ошибки в код клиента.(Конечно, когда-нибудь вы сможете опубликовать новую версию API (например, /api/v2 /), но даже в этом случае обратная совместимость скорее всего будет обязательной).

API везде!

По оценкам экспертов, к концу десятилетия пользователям будет доступно более 1 миллиона публичных API
По статистике, более 9 миллионов разработчиков вовлечены в создание внутренних API. Сегодня фокус сдвигается в сторону разработки публичных API
Интернет вещей (IoT) достигнет 20 миллиардов подключенных устройств к 2020 году
в 2016 году заплатила 625 млн. долл. за покупку поставщика платформы управления API фирмы Apigee.
Как рассказал руководитель центра консалтинга Aplana Амелин Владимир, в 2016 году число опубликованных Public API во всем мире достигло 16 тыс., а к 2020 г. их будет уже более 1 млн. В России их предоставляют «Яндекс», Mail.ru, «», «», в финансовой сфере — Сбербанк, ФК «Открытие», «Тинькофф Банк», ВТБ, а также крупные розничные сети, сервисы госуслуг и открытого правительства. Согласно проведенному опросу, 26% отечественных банков разработали или разрабатывают собственные API, еще 38% планируют сделать это в следующем году. По данным Gartner, 75% банков из мирового списка Top 50 уже имеют собственные открытые API, а к 2018 г. регуляторы половины стран G20 примут стандарты, регулирующие их применение. Разновидностью Public API являются интерфейсы категории Open API, базирующиеся на открытых стандартах и доступные широкому кругу разработчиков, как правило, на бесплатной основе. По словам Владимира Амелина, рост их популярности связан с тем, что все больше компаний видят в них потенциал для развертывания новых бизнес-моделей и понимают, как такие модели монетизировать.

Тестирование API без документации

Если Вам по какой-то причине предстоит проделать эту неблагодарную работу,
определетесь, насколько всё плохо. Какая у Вас есть информация об объекте
тестирования.

Известно ли какие порты для Вас открыты? Знаете ли Вы нужные endpoints?

Сканирование портов

Если дело совсем труба — просканируйте порты, например, с помощью netcat.
Открытые порты сохраните в файл

openports.txt

nc -z -v answerit.ru 1-10000 2>&1 | grep succeeded > openports.txt

Эта операция займёт довольно много времени. Можете почитать советы по работе с

Nmap и Netcat

, например, следующие:

Перебор запросов

Если Вам известен нужный порт и соответствующий endopoint переберите все возможные HTTP
. Начните с наиболее очевидных:

POST
PUT
GET

Для ускорения процесса напишите скрипт на

Bash

или

Python
.

В худшем случае, когда ни порт ни endpoints неизвестны Вам, скорее всего придётся перебирать
все открытые порты и генерировать endpoints, которые подходят по смыслу.

Разработчики обычно не особо заморачиваются и закладывают минимально-необходиму информацию.
Так что включите воображение и попробуйте придумать endpoints опираясь на бизнес логику
и принятые в Вашей компании стандарты.

Если ни endpoints ни бизнес логика Вам неизвестны, то у меня есть подозрение, что Вы
тестируете API с не самыми хорошими намерениями.

Плюсы и минусы работы с API

Плюсов у использования API немало:

Самый главный плюс работы с API – это экономия времени при разработке собственных сервисов. Программист получает готовые решения и ему не нужно тратить время на написание кода для функционала, который уже давно реализован.
В API могут учитываться нюансы, которые сторонний разработчик может не учесть или просто не знать,
API дает приложениям определенную системность и предсказуемость – одна и та же функция с помощью API может быть реализована в разных приложениях так, что будет понятна и знакома всем пользователям.
API дает сторонним разработчикам доступ к закрытым сервисам.

Но также есть и минусы:

Если в основной сервис вносятся изменения и доработки, в API они могут попасть не сразу,
Разработчику доступны готовые решения, как именно они реализованы и как выглядит исходный код, он не знает,
API предназначен в первую очередь для общего использования, он может не подойти для создания какого-то особого функционала.

Заключение

Нужно держать круговую оборону и защищаться со всех сторон. Как ни банально звучит, но безопасность системы определяется самым слабым звеном. И если мы забыли защитить даже незначительную часть, последствия могут быть весьма печальными.
Разработчик API должен не только уметь программировать, но и разбираться в безопасности систем и приложений. Или в команде должен быть сотрудник, отвечающий за безопасность.
Нужно следить за актуальным положением дел с безопасностью, т.к. даже относительно свежая информация может быстро устареть, и система окажется неработоспособной или беззащитной перед атаками.