Шаг 3 Параметры (Описание API)

Шаг 3 «Параметры (Описание API)»

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

• параметры заголовка,
• параметры path,
• параметры строки запроса,
• параметры тела запроса.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Параметры заголовка

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

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

Параметры path

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

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

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

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

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

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

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

Параметры строки запроса

Параметры строки запроса указываются после знака вопроса ? В конечной точке. Знак вопроса, параметры, которые следуют за ним и их значения, называется «строкой запроса». В строке запроса каждый параметр перечисляется один за другим с амперсандом & , разделяющим их. Порядок параметров строки запроса не имеет значения.

Эта строка запроса:

вернут один и тот же результат.

Однако в параметрах path порядок имеет значение. Если параметр является частью фактической конечной точки (не добавляется после строки запроса), это значение обычно описывается в описании самой конечной точки.

Параметры тела запроса

Часто с запросами POST (где мы что-то создаем) мы отправляем объект JSON в теле запроса. Этот параметр и есть тело запроса. Обычно форматом тела запроса является JSON. Этот JSON объект может быть длинным списком пар ключ-значение с несколькими уровнями вложенности.

Например, конечной точкой может быть что-то простое, например /surfreport/ . Но в тело запроса мы можем включить объект JSON со многими парами ключ-значение, например:

Документирование параметров тела сложного запроса

Документирование данных JSON (как в параметрах тела запроса, так и в ответах) является одной из самых сложных частей документации API. Документирование JSON объекта будет легким, если этот объект прост, с несколькими парами ключ-значение на одном уровне. Но если у нас есть JSON объект с несколькими объектами внутри объектов, множественными уровнями вложенности и большими объемными данными, это может быть сложно. И если объект JSON занимает более 100 строк, или 1000, нам необходимо тщательно продумать, как представить информацию.

Таблицы хороши для документирования JSON, но в них трудно различать элементы верхнего уровня и подуровня. Объект, который содержит объект, который также содержит объект, и другой объект и т. Д., Может сбивать с толку.

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

Взгляните на ресурс eBay findItemsByProduct. Вот параметр тела запроса (в данном случае формат XML):

Ниже параметра тела запроса находится таблица, которая описывает каждый параметр:

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

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

Подход Swagger к параметрам тела запроса

Пользовательский интерфейс Swagger, который мы рассмотрим позже, а также его демо, предоставляет другой подход к документированию параметра тела запроса. Swagger UI показывает параметры тела запроса в формате, который вы видите ниже. Интерфейс Swagger позволяет переключаться между представлением «Пример значения» и представлением «Модель» для ответов и параметров тела запроса.

Посмотрим на Swagger Petstore для изучения. “Пример значения” показывает образец синтаксиса вместе с примерами. При нажатии на ссылку “Модель””, видим пример параметра тела запроса и описания каждого элемента.

Модель включает в себя переключатели «развернуть / свернуть» со значениями. (Демо Petstore не имеет множество описаний параметров в модели, но если включить описания, они будут отображаться в модели, а не в примере значения.)

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

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

Параметры конечной точки SurfReport

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

Параметры

Параметры path

Параметры строки запроса

Следующие шаги

После того, как мы задокументировали параметры пора посмотреть на Пример запроса к ресурсу

Управление СВОЙСТВАМИ страниц и разделов | 1С Битрикс

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

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

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

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

Система битрикс позволяет проводить следующие манипуляции с заголовками сайта:

• составление одинаковых заголовков;
• установление различных свойства для страниц;
• устанавливать динамические мета-данные;

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

Управление свойствами страниц битрикс

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

Нам появилась форма для заполнения, давайте более детальней разберем ее поля:

• Заголовок – заголовок самой страницы, он же может быть title если не заполнено свойство «Заголовок окна браузера», а также подставляется как h1, которое видите на страничке;
• Описание страницы – это описание самой страницы description то самое описание, которое поисковики могут взять как краткое содержание текста на странице;
• Ключевые слова – keywords, перечисляем тут ключевые словосочетания.
• Заголовок окна браузера – он же title, если поле не заполнено, то значение в title подставляется из поля «Заголовок»;
• Продвигаемые слова – тут можно прописать слова, по которым планируете продвигать страницу, далее эти слова можете использовать в свое усмотрение, играясь с логикой и функционалом самого сайта.
• ROBOTS – в данное поле прописываем служебную информацию да роботов поисковых систем;
• Теги – в данном поле прописываем слова для использования по ним поиск данной страницы, так же учитывайте, что поиск дополнительно нужно настроить, что бы он корректно работал.

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

Управление свойствами раздела

Для этого в административном меню кликнем по кнопке «изменить раздел» и из списка выберем «Свойство раздела» или можно вызвать простым нажатием на иконку «Изменить раздел». В данной форме устанавливаем нужный нам заголовок. Сохраняемся и данные применились к страничке сайта.

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

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

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

Если на странице представленная динамическая информация из инфоблоков, то «заголовок» и «ключевые слова», а также описание для таких разделов могут устанавливаться автоматически из инфоблоков. Для этого в самом компоненте необходимо произвести соответствующие настройки, а в инфоблоке можно настроить метаданные на закладке SEO, тогда на странице мы сможем вывести тот результат, который нам нужен. Как настраивать SEO данные мы будем разбирать более подробнее в скором времени.

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

Универсальные списки — использование для простого добавления элементов с модерацией

Модуль "Универсальные списки" — достаточно мощный и функциональный. Его можно с успехом использовать для предоставления пользователям сайта возможности добавлять и редактировать свои элементы инфолока в публичной части. Однако принцип работы с ним сильно отличается от того, к чему мы привыкли, работая, например, с компонентом "Добавление элементов инфоблока". Прежде всего это касается настройки прав доступа. В этой статье я расскажу как настроить модуль для выполнения задачи, аналогичной той, которая раньше решалась с помощью компонента "Добавление элементов инфоблока", т.е. чтобы пользователь мог добавлять элементы инфоблока, и редактировать элементы, но только добавленные им самим, с возможностью модерации редактором сайта.
[spoiler]
1. Создаем тип инфоблока

Т.к. комплексный компонент "Универсальные списки" (bitrix:lists) не работает с отдельными инфоблоками, cоздаем тип инфоблока "Компании".

2. Настраиваем тип инфоблока для работы с универсальными списками

Для этого заходим в настройки модуля "Универсальные списки" (Настройки > Настройки продукта > Настройки модулей > Универсальные списки) и на вкладке "Права доступа" разрешаем группе "Администраторы" управлять списками в нашем созданном типе инфоблока "Компании".

Этот шаг обязателен, т.к. без него при размещении компонента наш тип инфоблока не появится в выпадающем списке в параметрах компонента.

3. Размещаем компонент

Создаем на сайте раздел, и размещаем в нем компонент "Универсальные списки".

В параметрах компонента выбираем наш тип инфоблока и включаем поддержку ЧПУ (в режиме не-ЧПУ лично мне не удалось заставить компонент работать).

Добавляем инфоблок (список)

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

Нажимаем кнопку "Добавить". Откроется форма добавления инфоблока.

На вкладке "Доступ" устанавливаем для группы "Зарегистрированные пользователи" право "Добавление", а для категории пользователей "Автор" — право "Изменение". Последнее даст возможность пользователю редактировать свои элементы. Если же установить для группы "Зарегистрированные пользователи" право "Изменение", то пользователь сможет редактировать все элементы инфоблока, а не только свои. Вместо группы "Зарегистрированные пользователи", можно также использовать категорию "Все авторизованные пользователи".

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

После выполнения данных действий, пользователи группы "Зарегистрированные пользователи", увидят следующее на главной странице раздела:

При выборе инфоблока (списка) "Компании", пользователю будет доступен список его элементов.

При нажатии кнопки "Добавить компанию", откроется форма редактирования:

Интерфейс добавления полей один для собственно полей и свойств инфоблока. При этом можно задать собственное название для любого поля, как и в компоненте "Добавление элементов инфоблока".

Отправка уведомлений и утверждение

Отправка уведомлений администратору сайта и утверждение документов при работе с универсальными списками как правило осуществляется с помощью бизнес-процессов. Т.к. использовать стандартные бизнес-процессы в данном случае не представляется удобным, то придется создать свой бизнес-процесс. Можно также использовать вместо бизнес-процессов модуль "Документооборот", но настраивать инфоблок на работу с документооборотом придется через административную часть битрикс, т.к. в компоненте "Универсальные списки" такая возможность отсутствует).

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

После нажатия на кнопку мы увидим список шаблонов бизнес-процессов.

Нажимаем кнопку "Создать последовательный бизнес-процесс". Откроется страница редактирования шаблона бизнес-процесса.

Это немного модифицированный стандартный бизнес-процесс "Утверждение по первому голосу". Т.к. стандартный механизм публикации использовать не удалось — при снятии с публикации, элементы не отображаются в списке (даже под админом), я использовал вместо блоков "Публикация"/"Снятие документа с публикации" блоки "Изменение документа" с простой активацией/деактивацией. Кроме того, вместо почтовых сообщений, я использовал сообщения соцсети.

В параметрах шаблона устанавливаем галочку "Автоматически запускать при добавлении".

Если же установить галочку "Автоматически запускать при изменении", то процесс будет запускаться пользователем при изменении элемента. Либо можно создать для этого отдельные бизнес-процесс, который будет функционировать по другому сценарию, например, не деактивировать элемент, а просто отправлять уведомление редакторам сайта.

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

Правка шаблона компонента

Правка шаблона компонента в нашем случае будет сводится в основном к упрощению и отключению лишнего функционала.

Например, чтобы изменить внешний вид списка по умолчанию (по умолчанию отображаются все колонки полей, цветовая схема — синяя), добавим в шаблон компонента lists.list в файл result_modifier.php, следующий код:

Данный код установит вывод только колонок "Название", "Бизнес-процессы", серую цветовую схему и пр. Если же пользователь уже выбирал колонки или что-то другое, его выбор не будет изменен.

В том же файле result_modifier.php убирем ссылку на бизнес-процесс в списке, оставляем только название. Само название колонки "Бизнес-процессы" меняем на "Статус". Таким образом в этой колонке будет отображаться статус бизнес-процесса, например, мы можем в самом бизнес-процессе устанавливать статусы "На модерации", "Опубликован", "Отклонен".

Чтобы убрать возможность запуска бизнес-процесса из контекстного меню, в том же файле вставляем код:

Теперь правим шаблон компонента lists.element.edit — полностью убираем вкладки "Бизнес-процессы" и "Разделы". Для первого достаточно найти в файле template.php конструкцию CModule::IncludeModule( "bizproc" ) и подставить рядом с ней " && false", для второго — найти и закомментировать строку:

В целом использование модуля "Универсальные списки" для решения данной простой задачи не является оправданным и даже удобным (пришлось выполнять слишком много действий, не обошлось без правки шаблона компонента). Компонент "Добавление элементов инфоблока" гораздо лучше подходит для этого, если бы не одно но — этот компонент больше не поддерживается компанией 1С-Битрикс, и самые простые вещи приходится дорабатывать почти с нуля. Поэтому во многих случаях описанный метод может иметь преимущества.

Примечание: статья написана на основе опыта работы с модулем "Универсальные списки" версии 11.5.1

Настройка параметров в K2

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

Макет и Отображение

Настройки CSS

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

Макет и отображение страниц пользователя (автора)

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

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

Поля, которые будут доступны на странице вывода материалов по тегу. А также определение количества в списке тегов и их сортировка.

Макет и опции отображения для страниц поиска, Тег & Дата списков

Определение количества материалов, которые будут отображаться в результатах поиска, тегов и по дате. И выбор полей, отображаемых на этих страницах (заголовок, дата, вступительный текст, RSS и т.д.)

Уникальный момент, а также полностью готовый сайт вы можете заказать после перехода по ссылке — http://zakazatsayt.kiev.ua/

Контент

RSS-каналы

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

Очистка содержимого

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

Доп поля

Установка размеров (ширины/высоты) для всплывающих окон дополнительных полей.

Изображения

Общие настройки для изображений:

• установка качества картинок
• ширина/высота для маленького/среднего/большого изображений
• ширина изображения случайного материала
• ширина изображения категории
• ширина изображения пользователя в профиле и комментариях (аватар)

Онлайн-редактор изображений

Выбор из выпадающего списка онлайн-редактора, который будет запускаться из модуля K2 Quickicons.

Расширенные настройки изображения

Можно установить дату изменения изображения в URLе картинки. То есть, если открыть изображение в новом окне, то ссылка будет содержать дату. Так же здесь можно увеличить количество памяти, затрачиваемое на обработку изображения, но делать это нужно с осторожностью.

Социум

Здесь можно вставить HTML код для социальных закладок типа — Add this и Share this. Также для персонализации кнопки Twitter нужно указать свой аккаунт.

Комментарии

Для комментариев устанавливается способ показа на сайте, количество для показа, возможность автопубликации, присутствие ReCaptcha и др.

Редактирование с лицевой части

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

Расширенные

Использовать одно окно редактора для вводного и полного текста — для добавления вводного и полного текста можно установить раздельные окна
• Состояние по умолчанию для боковой панели материала — выбрать показывать или нет боковую панель
• Изменение корневой папки вложений — загружаемые вложения по умолчанию хранятся в папке по пути: media/k2/attachments, которую можно изменить.
• Скрыть кнопку импорта — иконки импорта пользователей и материалов можно скрыть
• Система тегов — автоматическое заполнение тегов или теги основаны на выборе
• Заблокированные теги — запретить создание тегов и отключить свободное тегирование
• Разрешить фильтрацию материалов по тегам — возможность фильтра по тегам на сайте
• Интеграция Google поиска — при выборе Google, обычный поиск будет отключен
• ID контейнера для Google search — установить уникальный id для поиска Google
• Включить К2 Профиль пользователя — при включении профиль пользователя будет иметь шаблон K2
• Выберите группу K2 по умолчанию для новых пользователей — группа для зарегистрированных
• Перенаправление на редактирование профиля — выбрать пункт меню, куда будет перенаправлен пользователь после изменения профиля
• Управление поиском материалов — поиск по заголовку или по всем словам
• Cookie домена — если ввести домен сайта, то у зарегистрированных пользователей в ссылке на профиль появится уникальный ID

Настройка Анти-спама

Установка защиты от спама:

• Для получения ключей ReCapthca нужно пройти регистрацию на сайте www.google.com/recaptcha
• Защита от спам-ботов с помощью сервиса StopForumSpam.com

Производительность

Отключение функций Счетчика материалов в категории и Отображение материалов из родительских и подкатегорий приводит к повышению производительности сайта. А отключение уплотнения порядка улучшит производительность с тысячами материалов.

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

Интеграция с sh404SEF

Если установлен компонент Sh404SEF, то параметры, находящиеся здесь, нужны для настройки взаимодействия с K2.