Как запустить api приложения
В этом большом гайде мы разберем тестирование API с помощью Postman. Он покроет большинство сценариев использования этой программы в вашей повседневной работе.
Давным-давно Postman стартовал как расширение для Google Chrome. Сейчас это полноценное нативное приложение, доступное на Windows, Linux и MacOS.
Что такое API?
Что такое Postman?
Зачем использовать Postman?
Установка Postman
Установка подробно описана в отдельном гайде. Найти его можно здесь (! на английском)
После того, как Postman установлен, можно переходить к тестированию API.
Postman отличный инструмент для тестирования API для тех, кто не хочет или не может писать тесты вручную (в IDE на языке программирования, используемом для разработки приложения).
Особенности Postman
Ниже мы перечислим только некоторые из особенностей Postman:
- Простой в использовании API клиент
- Функциональный и приятный UI.
- Может использоваться как для ручного, так и для автоматизированного тестирования API.
- Поддерживает интеграции с другими инструментами (например, поддерживает Swagger и RAML)
- Может быть запущен в Windows, Linux, MacOS.
- Не требует знания языков программирования.
- Предоставляет возможность легко экспортировать коллекции запросов, наборы тестов. Можно легко обмениваться этими данными с коллегами.
- Интегрируется с CI/CD инструментами (например, с Jenkins, TeamCity и т.п.)
- API Posman-a подробно документирован.
- Позволяет выполнять API автотесты.
Цена: Бесплатно или 21 доллар за пользователя в месяц.
Как пользоваться Postman
Для начала, давайте подробно рассмотрим интерфейс. Мы сознательно будем рассматривать английскую версию (и рекомендуем использовать именно ее):
Основные сущности Postman: запросы, коллекции и окружения
Перед тем, как приступить непосредственно к тестированию, давайте рассмотрим основные сущности, которыми оперирует Postman:
1. Запросы (Requests)
Запрос представляет собой комбинацию URL, хедеров и Body (тела запроса). Postman позволяет сохранять запросы и использовать их в будущем там, где вам нужно.
Как мы писали выше, Postman позволяет делать запросы к API. С помощью API-запроса можно получать и отправлять данные какому-либо бэкенд-сервису.
- GET: GET-запросы используются для получения данных от API.
- POST: POST-запросы используются для отправки новых данных API.
- PUT: PUT-запросы используются для обновления уже существующих данных.
- PATCH: PATCH-запросы (как и PUT) используются для обновления уже существующих данных. Разница в том, что с помощью PATCH запросов можно обновить несколько записей за раз.
- DELTE: DELETE-запросы используются для удаления существующих данных.
Далее в статье мы рассмотрим, как создавать и отправлять запросы разных типов с помощью Postman.
2. Коллекции (Collections)
Коллекции представляют собой группы запросов. Вы можете думать о коллекциях как о папках, в которых лежат запросы.
Как создать коллекцию в Postman:
Введите имя (Name) и описание (Description) коллекции, после этого нажмите кнопку Create:
Коллекция может содержать любое число запросов. Запустить выполнение коллекции можно двумя способами:
- с помощью Collection Runner
- c помощью Newman
Далее мы рассмотрим оба этих способа.
3. Окружение (Environments)
Мы рассмотрим работу с окружениями далее в статье.
Тестирование GET-запросов
Повторимся, GET-запросы используются для получения данных с сервера. GET-запросы не меняют состояние данных на сервере (не добавляют, не удаляют и не изменяют данные).
Давайте отправим GET-запрос с помощью Postman:
Мы рекомендуем завести аккаунт и использовать его для входа (чтобы сохранять запросы, коллекции и окружения для использования в будущем).
Шаг 2: Создаем GET-запрос:
После выполнения запроса вы должны будете увидеть данные от сервера во вкладке Body.
На скриншоте ниже вы видите код ответа сервера (Status: 200 OK), время выполнения запроса (Time: 1700ms) и размер ответа (Size: 1.62 KB)
По наведению на Time и Size появляется всплывающее окно с подробной информацией.
Время ответа сервера (Response Time)
Размер ответа (Response Size)
Куки (Cookies): Здесь можно увидеть информацию о куках, возвращаемых сервером
Хедеры ответа от сервера (Response headers)
Тестирование POST-запросов
POST-запросы используются для отправки новых данных на сервер. Давайте попробуем с помощью POST-запроса добавить нового пользователя. Для этого мы отправим информацию о новом пользователе в теле POST-запроса.
После этого наживаем кнопку SEND и отправляем POST-запрос.
Примечание: для проверки корректности вашего json можно использовать Jsonformatter
Точно так же, как и POST, отправляются PUT, PATCH и DELETE запросы.
Примечание: во время тестирования, для каждого запроса проверяйте возвращаемый результат, код ответа сервера и время ответа сервера. И не забывайте про негативные тесты!
Параметризация запросов
Часто необходимо выполнить один и тот же запрос на разных наборах данных. С помощью параметризации, можно использовать переменные при выполнении запросов.
В Postman, параметры создаются с помощью двойных скобок: >.
Шаг 2: Меняем URL на параметр >. После этого URL запроса должен быть таким: >/users
Шаг 3: Теперь нам нужно создать переменную окружения, чтобы использовать ее в качестве параметра. Для этого нажимаем на кнопку с глазом и кликаем на Edit (редактировать), чтобы создать глобальную переменную и затем использовать ее в коллекциях.
Если все сделано правильно, значение переменной, которую мы создали, будет подставлено вместо ее имени и запрос выполнится успешно.
Создание тестов в Postman
Тесты в Postman позволяют убедиться, что API работает так, как этого от него ожидают.
Давайте начнем с написания простого теста.
Код теста будет выглядеть следующим образом:
Запуск коллекций с помощью Collection Runner
Давайте запустим коллекцию с помощью Collection Runner.
Шаг 2: Должна будет открыться следующая страница:
Разберем основные элементы:
Шаг 3: В этом окне добавим коллекцию для запуска. Выбираем нашу коллекцию тестов, устанавливаем параметр Iterations в 2, delay в 2500ms и нажимаем кнопку запуска.
Запуск коллекций с помощью Newman
Для того, чтобы запустить коллекции с помощью Newman, делаем следующее:
Шаг 1: Устанавливаем node.js. Сделать это можно по ссылке
Шаг 2: Открываем командную строку и выполняем команду npm install -g newman
Шаг 3: После установки newman заходим в Postman. В списке коллекции находим нашу коллекцию, нажимаем на три точки и выбираем Export (Экспортировать)
Шаг 5: Выбираем папку, в которую экспортировать коллекцию и нажимаем Save. Рекомендуем создать отдельную папку для Postman-тестов. После нажатия на Save, коллекция будет экспортирована в выбранную папку.
Шаг 6: Для корректного запуска нам понадобится экспортировать и окружение. Для этого нажимаем на кнопку с глазом и выбираем опцию Download as JSON. Выбираем папку, в которую экспортировать окружение и нажимаем Save. Рекомендуем экспортировать окружение в ту же папку, в которую была экспортирована коллекция.
Шаг 7: Теперь, когда мы экспортировали коллекцию и окружения в папку, возвращаемся в командную строку и меняем директорию на ту, где находятся коллекция и окружение.
Шаг 8: Запускаем коллекцию с помощью команды:
newman run PostmanTestCollection.postman_collection.json -e Testing.postman_globals.json
После выполнения коллекции, появятся результаты выполнения тестов.
Заключение
В этом гайде по Postman мы постарались разобрать базовые темы. Мы надеемся, вы научились создавать и отправлять просты запросы, проверять ответы сервера, создавать простые тесты. Узнали, как выполнять коллекций с помощью Collection Runner и Newman. В следующих статьях мы разберем продвинутые возможности Postman.
На заре программирования и до совсем недавнего времени программа была чем-то законченным, полностью готовой к употреблению самостоятельной единицей, которая выполняла свои функции и только их.
Однако с появлением мобильных устройств, веб сайтов с богатой логикой и социальных сетей все стало меняться. Сейчас программы, которые не выходят в сеть, не умеют что-то выкладывать в фейсбуки и вообще работают сами в себе, практически не имеют права на жизнь. Даже професcиональные инструменты, такие как, Microsoft Office 2013, стали поддерживать облачные хранилища для обмена документами.
Мир меняется. Теперь, чтобы заработать денег на продаже софта, необязательно писать свою собственную операционную систему или антивирус, потратив кучу времени и ресурсов. Достаточно просто попросить свою жену и вдвоем разработать мировой хит. Поэтому многие сегодня мечтают создать своих злых птичек или кат-зе-роуп, изучая разработку под iOS, Android, Windows Phone.
И все вроде бы выглядит хорошо и уже кажется, что решение найдено. Однако проблемы начинаются, когда вы станете самостоятельно развертывать сервис бекенда на сервере. Я — программист, и когда дело доходит до установки и настройки сервера, мне сразу становится не по себе. Во-первых, это абсолютно новые знания, которые надо изучить, чтобы все работало как надо. Во-вторых, чтобы все работало действительно как надо и не упало при возросшей нагрузке или атаке, надо курить маны еще больше и упорнее. Можно попробовать найти такого хостера, который избавит вас от возни с серверами и предустановит PHP и/или что-то еще. Но тогда останется проблема того, что нужно будет самостоятельно реализовывать все необходимые обработчики событий сервера для реализации полноценного REST API. А это опять же отнимает ваше полезное время и тратит его на ненужные вещи.
К чему я это все?
Данный сервис, наряду с другими полезными возможностями Windows Azure Mobile Services, является PaaS решением и предоставляет возможность быстро развернуть облачный RESTful API, к которому может получить доступ программа на любом языке и платформе. В основу этого решения легла уже не новая, но довольно популярная технология Node.js. Custom API является полностью функциональным Node.js приложением со всеми вытекающими последствиями — это полноценное решение без компромиссов. А с учетом того факта, что для работы с ним написаны нативные SDK для всех трех популярных мобильных платформ, это решение становится еще интереснее.
Далее в этой части я хочу рассказать о том, как создать и начать пользоваться облачным бекендом в Windows Azure и обращаться к нему с мобильного устройства. Не переключайтесь!
Создание облачного бекенда
Создание облачного бекенда, как и любого другого сервиса в Windows Azure, происходит из портала управления облаком. Сперва надо создать мобильную службы, придумав ей какое-то вменяемое название:
Далее вам необходимо выбрать SQL базу данных, в которой будут храниться данные мобильной службы. Есть вариант создать бесплатный экземпляр на 20Мб. Для тестирования возможностей — хватит за глаза. А если понравится, то всегда можно проапгрейдиться на более серьезные решения.
После нажатия на стрелку далее и ввода параметров сервера БД (создать новый или использовать существующий логин/пароль администратора и прочая скукота), новый мобильный сервис начнет создаваться в облаке. Обычно это происходит крайне быстро, меньше чем за минуту. Когда служба создастся и вы зайдете в нее, то увидите что-то вроде этого окна:
Запомните его, оно нам еще пригодится далее.
Создание API
Чтобы создать свой первый облачный API, просто перейдите на вкладку API и нажмите кнопку Create a Custom API:
Если вы ранее работали с мобильными службами Windows Azure, то следующее окно будет вам знакомо. В нем необходимо задать название будущего API, а также один из четырех уровней доступа к различным его методам. Оставим все по умолчанию, тогда к нашему API смогут подключаться только те клиенты, у которых есть параметр авторизации:
Как только новый API создался, мы можем приступить к его редактированию. Изначально вы должны увидеть скрипт, похожий на этот:
В образовательных/тестовых целях я предлагаю слегка его изменить, чтобы получилось вот так:
Основным изменением в данном случае стало то, что в обработчике POST-запросов стали возвращаться данные в виде простой строки, а в GET добавилась переменная, и у ее объекта есть более одного поля. Я сделал так для наглядности, чтобы проиллюстрировать различные возможности работы с данными.
Использование API
Для данной статьи мы воспользуемся тестовым приложением, которое нам любезно предоставляет Windows Azure Mobile Services. Для этого вернемся на страницу Quick Create (это та самая, с облачком и молнией на пиктограмме), выберем Windows Phone 8 (хотя обратите внимание на богатый выбор) и нажмем Create A New Windows Phone App:
Создав нужную табличку (TodoItem) и скачав приложение по кнопке Download, откроем его в Visual Studio.
В первую очередь нас интересует две вещи. В файле App.xaml.cs есть строка примерно такого вида:
С помощью этого поля мы будем общаться с нашей новоиспеченной мобильной службой. Набор непонятных символов — это ApplicationKey, индивидуальный ключ вашей службы, хольте его и лелейте.
Давайте запустим приложение и посмотрим хотя бы, как оно выглядит:
Ну не хит апстора, но для начала неплохо. Давайте наделим его дополнительной логикой и вызовем наши API методы. Идем в файл MainPage.xaml.cs. От него я хочу добиться того, чтобы при нажатии на кнопку Save происходило обращение к сервисам, после чего полученный результат просто писался в консоль отладки. Для этого в конец метода InsertTodoItem добавьте следующий код:
Главным методом в этом коде можно назвать InvokeApiAsync. Он отвечает за вызов того или иного метода API. Этот метод перегружен и наделен различным набором параметров. В примере видно, что в случае с POST мы передаем аж 5 параметров, а в случае с GET всего 3. Это связано с тем, что метод для POST рассчитан на то, что результатом работы будет обычная строка (вспоминаем реализацию скрипта на бекенде), а вариант с GET — на работу с JSON объектом (результатом будет Newtonsoft.Json).
Если теперь запустить приложение и понажимать кнопку Save, то в Debug-консоли приложения будет видно что-то вроде этого:
Как у них
Я не просто так попросил обратить внимание на возможность выбора типа приложения на страничке Quick Create в панели управления Windows Azure. Дело в том, что нативный SDK для работы с мобильными службами написан не только для Windows устройств. Свои библиотеки выпущены и для iOS, и для Android, поэтому все то же самое можно использовать и на этих платформах. Вот пример кода на ObjectiveC, который будет делать примерно то же, что и в примере:
Как видите — «чистый» ObjectiveC, без мухляжа. Аналогично для Android, WinRT и даже для веб-версии (на HTML и JavaScript).
API или Application Programming Interface можно встретить в большинстве современных приложений и вебсайтов. Уже из названия понятно, что это интерфейс, предлагающий разработчикам готовые блоки для создания приложений. Когда ты пишешь приложение, ты обращаешься к такой «библиотеке» и берешь оттуда необходимые данные.
Пока что все выглядит просто и понятно. Надеемся, что так будет и в дальнейшем и ты быстро разберешься в теме и научиться применять API в своих приложениях. А если нет, то мы постараемся помочь тебе в понимании того, что такое Application Programming Interface и где он применяется.
Что же такое Интернет? Это огромная сеть серверов, связанных между собой. На них и хранятся все сайты, которые ты можешь видеть, когда вводишь определенный УРЛ в строку браузера. В принципе, сервером может стать и твой рабочий ноутбук. Он будет обслуживать твой сайт в сети, например. Кстати, разработчики, работающие над сайтами, создают их на локальных серверах и только после отладки запускают во всемирную паутину для публичного доступа.
В некоторых компаниях API идет как готовый продукт. Например, если это метеорологический сервис, покупая доступ к Application Programming interface, ты получаешь метеорологические данные.
А теперь посмотрим на то, как можно использовать API в своих собственных приложениях. Один из самых простых примеров – написание приложения, в котором пользователь сможет получать данные по погоде в своем городе. Для этого нам необходимо подготовить HTML макет и подключить соответствующий API, а затем, с помощью нескольких функций заставить это приложение работать.
Как пишется HTML код под приложение, мы здесь разбирать не будем, в этом нет смысла. Приложение писалось в библиотеке React, поэтому тем, кто с ней еще не знаком, некоторые моменты могут быть не совсем понятны, но мы поясним по ходу разъяснения.
Итак, для получения доступа к серверу, мы сделаем функцию, в которой будет запрос к серверу с метеорологическими данными. Это нужно для того, чтобы в последующем, пользователь нашего приложения мог получать данные о погоде в любой момент.
Как это происходит? Пользователь твоего приложения хочет узнать, например, погоду в Москве. Для этого, он вбивает название города в поиск, который ты уже внедрил в приложение и получает результат.
В программе же этот результат достигается следующим образом. Функция getWeather отправляет запрос на сервер и получает ответ.
Дальше, в этой же функции мы спрашиваем, отвечает ли нам сервер. Если статус 404, значит мы не записываем никакие данные. А пользователь увидит undefined, ну или что-то другое, по твоему усмотрению. Если же сервер отвечает, мы записываем ответы в state и, когда пользователь будет вводить, например, «Москва» в поиске приложения, у него отобразятся данные именно по Москве (в нашем случае это температура, название города, страны, погодные условия)
Это пример на React, но ты можешь сделать все это на чистом JS без проблем. Самое главное – понять, как все это работает. Как ты мог убедиться, принцип здесь тоже очень простой – отправка запроса на сервер, получение статуса сервера. Если он недоступен, ты в приложении сообщаешь об этом пользователю, например, в графе «Температура» будет написано «Неизвестно» или любой другой вариант.
Если же сервер доступен, пользователь увидит температуру в своем городе, название города, страну и погодные условия.
А вот как выглядит API Европейского центрального банка. Его можно использовать, например, при создании простейшего конвертера валют. Как видишь, здесь просто объект, в котором есть стандартный набор ключ:значение. Получая доступ к этому серверу, ты можешь сделать конвертер, который поможет твоим пользователям рассчитать курс интересующих их валют.
И это далеко не все. Сегодня очень многие приложения и вебсайты предлагают свои API разработчикам. Например, такой интерфейс есть на сайте GitHub, где в базе можно получить информацию по всем пользователям и определенным критериям. API есть на криптовалютных биржах и с их помощью ты можешь создать свое приложение, которое будет «подтягивать» самые последние и актуальные котировки. Тот же CoinmarketCap работает по этому же принципу. Через Application Programming Interface они получают данные с большинства крупных и не только бирж о токенах.
Все интерфейсы разделен по категориям. То есть, если тебе нужны метео сервисы, ты просто находишь такую категорию и смотришь результаты.
После этого откроется страница, на которой будут представлены все API нужной категории.
Выбрав подходящий интерфейс, можно переходить к его описанию и документации. Она представлена следующим образом
Как видишь, все очень подробно. Очень многие API в свободном доступе, поэтому если ты сейчас изучаешь, например, JS или библиотеку типа React, ты можешь тренироваться с такими API в написании своих приложений для портфолио. Сервис требует регистрацию, пройти которую можно в том числе с помощью социальных сетей.
Существует два основных типа API – публичные и приватные. Первые встречаются в таких приложениях, как Slack или Shopify. Здесь разработчики делают упор на то, что интерфейсы могут использоваться на сторонних платформах. Подключение к такому API совершенно бесплатно, как и его использование.
Есть также приватные API. Они используются, в основном, внутри компаний. Если у фирмы множество внутренних продуктов, для взаимодействия между ними задействуется такой приватный интерфейс.
Самыми часто используемыми интерфейсами этого типа являются:
Наверное, ты уже понял, хотя бы отчасти, зачем приложению нужен API. Приведем наиболее частые ситуации, когда в твоих приложениях ты будешь использовать такой интерфейс:
- Мобильные приложения. Если ты заглянешь AppStore или Google Play Market, ты найдешь там множество софта, в котором используются API. То есть ты создал какую-то программу, сделал простой API и пользователи приложения будут получать информацию именно через этот интерфейс. Согласись, очень удобно и практично.
- Open Source. Почему бы не использовать нужды твоей аудитории тебе же на благо? Сделал приложение? Создай к нему API, с помощью которого пользователи смогут создавать новые клиенты и сервисы.
- Распределение фронтенд и бэкенд. Здесь речь идет о том, что сделать такое распределение можно, например, с помощью использования различных фреймворков для фронтенда.
В принципе. На этом можно было бы и закончить, ведь ты уже создал интерфейс, пусть, как говорится пользуются (платно или бесплатно, определять тебе). Но на самом деле, это недостаточно. Каким образом пользователи будут обращаться к интерфейсу?
Первое, что сразу же приходит на ум –Octokit от GitHub. Это яркий пример таких библиотек. Что касается документации, в ней содержится вся необходимая информация для того, чтобы пользователь библиотеки знал, как отыскать требуемую информацию.
Итак, если ты планируешь создание своего собственного API, возможно, тебе стоит позаботиться и о том, чтобы создать к нему библиотеки. Кстати, если твое приложение будет пользоваться большой популярностью, возможно, кто-то другой создаст библиотеку для работы с API твоего софта.
Наверняка ты видел на страницах с приложениями заветное слово API. Это значит, что ты можешь создать свое собственное приложение и использовать готовый API на определенных условиях (бесплатно, платно, за регистрацию и так далее).
В качестве примера, можно привести API Github. Здесь ты получишь всю информацию о пользователе, его аватарке, подписчиках, репозиториях и иные интересные данные. А если взять API Twitter, здесь можно получить информацию о пользователях, твитах, подписчиках и так далее. Такая информация может быть действительно крайне полезной при разработке сторонних приложений.
Теперь ты знаешь, что такое Application Programming Interface. Ты можешь применять его в своих приложениях или создать приложение и разработать свой API для него, чтобы другие пользовались им.
После раздела «Обзор API» обычно идет раздел «Начало работы», в котором подробно описываются первые шаги, которые пользователи должны пройти для использования API. Этот раздел часто включает весь процесс от начала до конца, сжатый настолько просто, насколько это возможно.
Цель раздела “Начало работы”
Раздел «Начало работы» это как `Hello World`, только с API. Сколько времени понадобится разработчику, чтобы получить максимально простой ответ, используя ваш API?
И Hello World и “Начало работы” преследуют одну и ту же цель: показать пользователю, как использовать инфраструктуру, API или какую-либо другую систему, для получения простого и легкого результата, чтобы пользователи получили полное представление о работе системы, API и т.д.
В качестве примера можно взять общий базовый сценарий использования API и показать, как создать запрос, а также какой ответ возвращается. Если разработчик сможет успешно выполнить такой вызов, значит и с остальными не должно возникнуть проблем.
Раздел “Начало работы” может содержать следующие пункты:
- Войти в аккаунт;
- Получить API ключ;
- Создание запроса
- Оценка ответа.
Поместите ссылку на раздел “Начало работы” на домашней странице документации. Сделайте так, чтобы разработчики могли с легкостью использовать API для получения определенного результата. Если подразумевается использование предварительно подготовленных учетных записей или конфигураций настройки, нужно продумать и это.
Кнопка Run in Postman
В разделе “Начало работы” можно рассмотреть возможность добавления кнопки Run in Postman . (Postman - это клиент REST API GUI, который мы изучили ранее в разделе Отправка запросов в Postman.) Если есть конечные точки API, интегрированные с Postman, можно экспортировать свои коллекции Postman в виде виджета для встраивания в HTML-страницу.
Run in Postman это кнопка, которая при нажатии импортирует информацию об API в Postman, чтобы пользователи могли выполнять вызовы с помощью клиента Postman. Таким образом, кнопка Run in Postman позволяет импортировать интерактивный пробный интерфейс API для конечных точек на веб-страницу.
Чтобы добавить кнопку Run in Postman , можно импортировать спецификацию OpenAPI в Postman или ввести информацию об API вручную. Стоит изучить раздел “Postman/docs”, как создать кнопку Run in Postman .
Множество демонстраций Run in Postman можно посмотреть здесь. Многие из этих демонстраций перечислены в сети API Postman.
сеть API Postman
Вот демо Run in Postman с использованием конечной точки weather API OpenWeatherMap (с которой мы работали раннее ):
Если нажать на кнопку, будет предложено открыть коллекцию в клиенте Postman:
Вариант открытия коллекции
Postman предоставляет мощный клиент REST API, с которым знакомы многие разработчики. Postman позволяет пользователям настраивать ключ и параметры API и сохранять эти значения. Хотя Postman не имеет возможности вызова в браузере, как в Swagger UI, во многих отношениях клиент Postman более полезен, поскольку позволяет пользователям настраивать и сохранять сделанные ими запросы. Postman - тот инструмент, который внутренние разработчики часто используют для хранения запросов API при тестировании и изучении функциональности.
Особенно, если ваши пользователи уже знакомы с Postman, Run in Postman является хорошим вариантом для пользователей, чтобы опробовать API, потому что он позволяет пользователям легко генерировать необходимый код для отправки запросов практически в любой язык. Это дает пользователям отправную точку, где они могут опираться на информацию для создания более подробных и настраиваемых вызовов.
Если в документации еще нет функции Try it out , кнопка Run in Postman предоставляет такую интерактивность простым способом, не требуя жертв со стороны единственного источника знаний для документации.
Недостатком является то, что в Postman не попадают описания параметров и конечных точек. Кроме того, если пользователи незнакомы с Postman, им может быть трудно понять, как им пользоваться. Редакторы Try it out , которые запускаются непосредственно в браузере, как правило, более просты и лучше интегрируют документацию.
Примеры разделов “Начало работы”
Ниже приведены несколько примеров разделов “Начало работы” в API. Если сравнить различные разделы «Начало работы», можно увидеть, что некоторые из них являются подробными, а некоторые - высокоуровневыми и краткими. В общем, чем дольше можно вести разработчика за руку, тем лучше. Тем не менее, раздел должен быть кратким, а не многословным с другой документацией. Ключевым моментом является то, чтобы показать пользователю полный, от и до, процесс работы с API.
Paypal
“Начало работы” Paypal содержит довольно много деталей, начиная с авторизации, запросов и других деталей до первого запроса. Хотя этот уровень детализации не так краток, он помогает сориентировать пользователей на необходимую им информацию. Чистый и понятный формат.
На стартовой странице Twitter есть несколько разделов, посвященных началу работы, для разных целей разработки. Текст лаконичен и понятен. В разделе размещены ссылки на другую документацию для получения более подробной информации. В целях краткости можно следовать такой же стратегии - быть кратким и ссылаться на другие страницы, которые содержат более подробную информацию.
Parse Server
Раздел “Начало” работы в Parse Server содержит большое количество деталей и подробное описание различных этапов. Для более подробных шагов по подключению вашего приложения и запуску сервера в другом месте, в разделе размещена ссылка на дополнительную информацию.
Adsense
“Начало работы” Adsense выделяет некоторые основные предпосылки для начала работы на платформе. После того, как вы настроитесь, он предоставляет «краткое руководство по началу работы». Такое руководство знакомит пользователей с простым сценарием от начала до конца, помогая им понять продукт и его возможности.
Aeris
Начало работы в сервисе погоды Aeris предоставляет информацию для настройки приложения, а затем делает запрос на одном из нескольких популярных языков. Хотя показ кода на определенных языках, несомненно, более полезен для программистов, использующих данный язык, примеры кода могут быть неуместны для других пользователей (например, разработчики Java могут найти код Python неуместным, и наоборот). Фокусировка на определенном языке часто является компромиссом.
Watson and IBM Cloud
В разделе “Начало работы” Watson и IBM Cloud перечислены три шага. Тем не менее, это не полное руководство по началу работы. Пользователь может только выбрать сервис для своего проекта. В итоге кодировать начинаем с помощью Watson Dashboard.
В идеале, раздел “Начало работы” должен помочь пользователю увидеть ощутимые результаты, но возможно ли это или нет, зависит от API.
👨💻 Практическое занятие: Раздел “Начало работы”
В своем найденном опен-сорс проекте найдем раздел “Начало работы” и ответим на следующие вопросы:
Читайте также: