Автоматизация для самых маленьких. заметки. restful 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 используются в Mobidea?

В Mobidea у аффилиатов есть возможность воспользоваться некоторыми API, которые нацелены на то, чтобы пользователи получали информацию как можно быстрее.

На данный момент у нас есть Statistics API, через который пользователи могут проверить статистику, и Offers API, в котором пользователи могут увидеть оферы.

Рассмотрим функциональность этих двух API более подробно!

Mobidea’s Statistics API

API статистики позволяет аффилиатам получать список со статистикой в выбранном формате (XML, JSON) для заданного дня (устанавливается в параметре &date) и доходом, показанным в выбранной валюте.

Список может быть настроен так, чтобы передавать только выбранные поля (дата, время, оператор, код страны, track1..track5, доход).

API оферов Mobidea

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

Данные в списке можно сортировать по статусу (в ажидании, одобрено или отклонено), категориям оферов и ограничениям.

Более того, пользователь может настроить данные так, чтобы передавать только выбранные поля (имя, описание, статус, категория, выплата, ограничения, иконка, баннеры, URL).

Аффилиаты могут использовать эти ссылки API для импорта данных на разные платформы и просмотра статистики продаж.

Эти API также помогают пользователям принимать различные решения, опираясь на сегмент с большим количеством продаж, на выплату офера или другие подобные детали.

Интегрируя API, предоставленные Mobidea, вы сможете просматривать как оферы, так и статистику, доступные в вашей любимой партнерской программе!

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

Независимо от типа параметра, определите следующее для каждого параметра:

Типы данных параметров

API могут некорректно обрабатывать параметр, если он имеет неправильный тип данных или неправильный формат

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

Вот типы данных наиболее распространенные в REST API:

• string: буквенно-цифровая последовательность букв и / или цифр;
• integer: целое число — может быть положительным или отрицательным;
• boolean: true или false значение;
• object: пара ключ-значение в формате JSON
• array: массив значений

Note: В программировании намного больше типов данных, и если имеются более конкретные типы данных, которые важно отметить, обязательно нужно их документировать. Например, в Java важно отметить допустимый тип данных, поскольку Java выделяет пространство памяти в зависимости от размера данных

Таким образом, Java получает гораздо более конкретную информацию о размере чисел. Есть byre, short, int, double, long, float, char, boolean и так далее. Однако, обычно, в REST API такой уровень детализации не нужно указывать.

Максимальное и минимальное значения параметров

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

Пропуск информации о максимальных / минимальных значениях или других недопустимых значениях является распространенной ошибкой в ​​документации. Разработчики часто не осознают всех «творческих» способов, которыми пользователи могут использовать API. Команда тестирования или обеспечения качества (QA), вероятно, является лучшим ресурсом для определения значений, которые не должны допускаться, потому что задача QA — попытаться взломать API.

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

О важности тестирования узнаем больше в модуле Тестирование документации.

# Какие дополнительные методы API нужно использовать при доставке товаров с 15 марта (FBS)

Изменения вступают в силу с 15 марта 2021 года.

Порядок использования дополнительных методов API распространяется только на FBS.

При работе через API с 15 марта 2021 года, вам нужно использовать дополнительные методы Seller API для некоторых служб доставки.
Какие именно методы, зависит от выбранной вами службы доставки.

Ozon Логистика

• Если у вас больше одного склада со способом доставки Ozon Логистика, то вам нужно печатать акт приёма-передачи на каждый метод на складах.
  Специально изменять статусы отправлений, получать данные или добавлять трек-номер через API вам не нужно, это будет делать Ozon.
  Используйте для печати актов методы API:
  • — выводит список складов.
  • — выводит список методов по каждому складу.
  • — формирует акт приёма-передачи для каждого метода на каждом складе.

Другая служба доставки или самостоятельно

• Для интегрированной, неинтегрированной или собственной службы доставки потребуется информация об отправлениях. Например, Ф.И.О. получателя и его контактные данные:

• Для интегрированной службы доставки вам нужно добавлять трек-номер к каждому отправлению. По трек-номеру Ozon будет отслеживать статус отправлений и показывать их в вашем личном кабинете и личном кабинете покупателя:

  POST /v2/fbs/posting/tracking-number/set — добавляет трек-номер к отправлению.

• Для неинтегрированной или своей службы доставки вам нужно изменять статусы отправлений у каждого заказа:

  • — изменяет статус на Доставляется.
  • — изменяет статус на Курьер в пути.
  • — изменяет статус на Доставлен.

• Если в вашем личном кабинете заведено больше одного склада, то вам нужно обновлять на них остатки:

  • — выводит список складов.
  • — обновляет количество товаров на складе.

Как работает API?

Теперь, когда мы установили, что API — это набор процедур, которые указывают программное обеспечение в правильном направлении, как именно это все работает?

Лучший способ объяснить основные функциональные возможности API — это привести пример из реальной жизни. Службы доставки еды, такие как GrubHub , сейчас невероятно популярны, поэтому давайте обсудим, как может работать код таких мобильных приложений.

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

Чтобы запланировать доставку, должно быть установлено соединение между веб-сайтом доставки и базой данных: веб-сайт является внешним интерфейсом, а база данных — внутренним. База данных — это то, что хранит данные для всех этих ресторанов, их доступность в зависимости от местоположения, график работы, меню и многое другое.

API — это связь между этой базой данных и веб-сайтом или приложением, которое представляет свои данные

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

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

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

Примеры API

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

VKAPI

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

Все запросы осуществляются к адресу https://api.vk.com/method/

После слэша идёт наименование используемого API-метода и передаются GET-параметры запроса. Ответ так же приходит по HTTPS в формате JSON.

TELEGRAM BOT API

Одно из самых популярных API. С его помощью осуществляется контроль ботов в мессенджере Telegram. После создания бота через @botfather и получения необходимых ключей доступа, вы можете начать взаимодействие с внутренним интерфейсом.

Запросы осуществляются по адресу

https://api.telegram.org/bot(token)/METHOD_NAME

Где token выражает секретный ключ.

Запросы посылаются через HTTPS соединения, название метода указывается через слэш к основному адресу. Ответ приходит в формате JSON.

OPEN WEATHER MAP API

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

Формат работа: HTTP передача по api.openweathermap.org/data/2.5/weather?id= c указанием идентификационного номера желаемого города. Ответ сервера: JSON.

GOOGLE MAPS API

Что может быть приятнее, чем интерактивная карта мира на сайте? Особенно, если это не шаблонная вставка из Google Maps, а ваша персональная редакция популярной карты с личными кластерами маркеров. Карта будет взаимодействовать с другими скриптами на сайте, посылая информацию о кликах и координатах.

Подобные возможности предлагает JavaScript API Google Maps. Модуль полностью скриптовой и работает на стороне браузера, поэтому HTTP-запросы из PHP и формирование заголовков на стороне сервера, как было в других API, нам не нужно.

Например, выставление метки на карте будет выглядеть так:

var mark = new google.maps.Marker({
position: myPOS,
map: map,
title:»Hello!»
});

Проблема документирования API

Документация API — это техническая (программная) документация, в которой указано как использовать API.
При этом эту документацию нужно поддерживать в актуальном стоянии чаще, чем любую другую. Ведь от актуальности документации API зависит качество разработки продукта. Однако, есть еще проблема разработки самого API системы. Любая система развивается, добавляются функции, изменяются существующие вызовы и методы. Но необходимо помнить о том, что с нашей системой могут быть интегрированы другие системы. И если изменения затронут API, то такая интеграция «развалится», при следующем обновлении произойдёт нарушение механизмов взаимодействия. Поэтому в документировании API можно выделить две основные проблемы:

1. Сложность написания документации API, так как это очень трудная тема. Неясно как писать, что писать и прочее. При написании возникает очень много вопросов. Тем более, если человек до этого никогда не имел дело с документированием API.
2. Поддержка документации API в актуальном состоянии.

Проблема стандартизации API

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

1. Пример полного запроса.
2. Примеры ожидаемого ответа.
3. Список кодов ошибок.
4. Удобный для поиска Web–интерфейс.
5. Предупреждения об изменении версии и расписание устаревания.

Способы создания документации API

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

Повторюсь, ведь от актуальности документации API зависит качество разработки ПО.

Одни из самых популярных спецификаций — это RAML, Swagger и API Blueprint.
Например, если программирование Системы происходи в MS Visual Studio, то в ней автоматически генерируется Xml (представлена на картинке ниже), с помощью которой уже можно создать в любой другой спецификации документацию API.

В данной статье разберём спецификацию Swagger, так как, на мой взгляд, она является более удобной для работы.
Когда понимание документирование API будет «на уровне», то можно уже выбрать любую другую программу, которая нравится больше, а для начала можно начать и с Swagger.

Тестирование 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 с не самыми хорошими намерениями.

Параметры path

Параметры path являются частью конечной точки. Например, в следующей конечной точке и являются обязательными параметрами path:

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

Цветовая кодировка параметра path

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

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

То позже можно использовать этот же цвет при описании этих же параметров.

Параметр URL	Описание параметра
	Описание параметра user
	Описание параметра bicycleId

Использование цвета для выделения параметров позволяет легко выделить определяемый параметр и его связь с определением конечной точки.

Пример API и тестовая матрица

Теперь мы можем отобразить все в виде матрицы и использовать ее для написания подробного плана тестирования (для автоматизации тестирования или ручных тестов).

Предположим, что подмножеством нашего API является конечная точка /users, которая включает следующие вызовы API:

Вызов API	Действие
GET /users	Просмотреть всех пользователей
GET /users?name={username}	Получить пользователя по имени пользователя
GET /users/{id}	Получить пользователя по ID
GET /users/{id}/configurations	Получите все конфигурации для пользователя
POST /users/{id}/configurations	Создать новую конфигурацию для пользователя
DELETE /users/{id}/configurations/{id}	Удалить конфигурацию для пользователя
PATCH /users/{id}/configuration/{id}	Обновить конфигурацию для пользователя

Где {id} — это UUID, а все конечные точки GET позволяют фильтровать, сортировать, исключать и ограничивать дополнительные параметры запроса для фильтрации, сортировки и разбивки на страницы тела ответа.

Основные позитивные тесты (позитивный путь по умолчанию)Позитивные тесты + необязательные параметры проверокНегативное тестирование – валидный ввод данныхНегативное тестирование — неверные входные данныеДеструктивное тестирование

Тест-кейсы, полученные из приведенной выше таблицы, должны охватывать различные потоки тестирования в соответствии с нашими потребностями, ресурсами и приоритетами (перевод таблицы в формате xls).

Выходим за рамки функционального тестирования

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

Уровни зрелости API

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

Безопасность и авторизация

• Убедитесь, что API разработан в соответствии с правильными принципами безопасности: отказ по умолчанию, безопасное падение сервиса, принцип наименьших привилегий, отклонение всех невалидных данных в запросе и т. д.

  • Позитивные тесты: убедитесь, что API отвечает на правильную авторизацию всеми согласованными методами аутентификации — ответный токен auth 2.0, файлы cookie, дайджест и т. д. — как определено в вашей спецификации.

  • Негативные тесты: убедитесь, что API отклоняет все несанкционированные вызовы.

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

Проверка протокола: проверьте HTTP / HTTPS в соответствии со спецификацией

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

Политики ограничения скорости, троттлинга и политики контроля доступа

Нагрузочные тесты (позитивные), стресс-тесты (негативные)

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

Избегайте частичных обновлений

Плохо:

— такой подход часто практикуют для того, чтобы уменьшить объёмы запросов и ответов, плюс это позволяет дёшево реализовать совместное редактирование. Оба этих преимущества на самом деле являются мнимыми.

Во-первых, экономия объёма ответа в современных условиях требуется редко. Максимальные размеры сетевых пакетов (MTU, Maximum Transmission Unit) в настоящее время составляют более килобайта; пытаться экономить на размере ответа, пока он не превышает килобайт — попросту бессмысленная трата времени.

Перерасход трафика возникает, если:

• не предусмотрен постраничный перебор данных;

• не предусмотрены ограничения на размер значений полей;

• передаются бинарные данные (графика, аудио, видео и т.д.).

Во всех трёх случаях передача части полей в лучше случае замаскирует проблему, но не решит. Более оправдан следующий подход:

• для «тяжёлых» данных сделать отдельные эндпойнты;

• ввести пагинацию и лимитирование значений полей;

• на всём остальном не пытаться экономить.

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

В-третьих, этот подход может как-то работать при необходимость перезаписать поле. Но что делать, если поле требуется сбросить к значению по умолчанию? Например, как удалить ?

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

Хорошо: можно применить одну из двух стратегий.

Вариант 1: разделение эндпойнтов. Редактируемые поля группируются и выносятся в отдельный эндпойнт. Этот подход также хорошо согласуется , который мы рассматривали в предыдущем разделе.

Теперь для удаления достаточно не передавать его в . Этот подход также позволяет отделить неизменяемые и вычисляемые поля ( и ) от изменяемых, не создавая двусмысленных ситуаций (что произойдёт, если клиент попытается изменить ?). В этом подходе также можно в ответах операций возвращать объект заказа целиком (однако следует использовать какую-то конвенцию именования).

Вариант 2: разработать формат описания атомарных изменений.

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

Примеры разделов “Начало работы”

Ниже приведены несколько примеров разделов “Начало работы” в API. Если сравнить различные разделы «Начало работы», можно увидеть, что некоторые из них являются подробными, а некоторые — высокоуровневыми и краткими. В общем, чем дольше можно вести разработчика за руку, тем лучше. Тем не менее, раздел должен быть кратким, а не многословным с другой документацией. Ключевым моментом является то, чтобы показать пользователю полный, от и до, процесс работы с API.

Paypal

“Начало работы” Paypal содержит довольно много деталей, начиная с авторизации, запросов и других деталей до первого запроса. Хотя этот уровень детализации не так краток, он помогает сориентировать пользователей на необходимую им информацию. Чистый и понятный формат.

Начало работы в Твиттер

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

Parse Server

Начало работы Parse Server

Раздел “Начало” работы в Parse Server содержит большое количество деталей и подробное описание различных этапов. Для более подробных шагов по подключению вашего приложения и запуску сервера в другом месте, в разделе размещена ссылка на дополнительную информацию.

Adsense

Начало работы Adsense

“Начало работы” Adsense выделяет некоторые основные предпосылки для начала работы на платформе. После того, как вы настроитесь, он предоставляет «краткое руководство по началу работы». Такое руководство знакомит пользователей с простым сценарием от начала до конца, помогая им понять продукт и его возможности.

Aeris

Начало работы Aeris

Начало работы в сервисе погоды Aeris предоставляет информацию для настройки приложения, а затем делает запрос на одном из нескольких популярных языков. Хотя показ кода на определенных языках, несомненно, более полезен для программистов, использующих данный язык, примеры кода могут быть неуместны для других пользователей (например, разработчики Java могут найти код Python неуместным, и наоборот). Фокусировка на определенном языке часто является компромиссом.

Watson and IBM Cloud

Начало работы Watson and IBM Cloud

В разделе “Начало работы” Watson и IBM Cloud перечислены три шага. Тем не менее, это не полное руководство по началу работы. Пользователь может только выбрать сервис для своего проекта. В итоге кодировать начинаем с помощью Watson Dashboard.

В идеале, раздел “Начало работы” должен помочь пользователю увидеть ощутимые результаты, но возможно ли это или нет, зависит от API.

10 занятных REST API

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

• PokeAPI. У крупнейшей медиа-франшизы всех времен есть простой способ получить данные о 800+ покемонах.
• NASA API. Получите данные об астероидах, галактиках и многом другом.
• Open Food Facts. Огромное количество данных о продуктах питания со всего мира.
• TransLoc OpenAPI. Получите живые данные об общественном транспорте городов и кампусов.
• Urban Dictionary API. Удивительно, какой сленг используют люди!
• Merriam-Webster Dictionary API. Для тех, кому нужны определения и синонимы реальных слов.
• Numbers API. Интересные факты и вопросы о числах.
• WeatherBit API. Текущие и исторические данные о погоде.
• US Government Data API. Достаточно большой набор данных о Соединенных Штатах — сельское хозяйство, здравоохранение, общественная безопасность и т.д.
• Bible API. Самая продаваемая книга всех времен. Величайшая история.

Типы API

Существует множество различных типов API для приложений, вебсайтов и операционных систем.

Среди определенных классов есть популярные Java API и интерфейсы, которые позволяют определенным субъектам обмениваться информацией на языке программирования Java.

Также есть и Web API.

Самые известные типы API:

• Удаленный вызов процедур (Remote Procedure Call – RPC)
• Простой протокол доступа к объектам (Simple Object Access Protocol – SOAP)
• Передача состояния представления (Representational State Transfer – REST)

Все еще недостаточно?

Больше примеров?

Подумайте о Windows, компьютерной операционной системе, разработанной Microsoft для работы с ПК (персональными компьютерами).

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

Более того, Windows – не единственная операционка, которая предоставляет API. Большинство ОС это делают.

Какая цель?

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

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