Авторизация  
VaM

VamShop 3 - API

Рекомендуемые сообщения

VaM

В VamShop 3 есть встроенный API с поддержкой JWT авторизации, т.е. с помощью токенов.

Доступ к API ограничивается с помощью токенов, т.е. это безопасный способ работы с VamShop 3 API.

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

Об этом всём в заметках ниже.

1. Инструменты, необходимые для работы с API.

Чтобы делать запросы к API (GET, POST, PUT, DELETE запросы) Вам нужно будет установить любой REST клиент.

Например это может быть Postman - https://www.getpostman.com/docs/introduction

или расширение для браузера Firefox - RestClient - https://addons.mozilla.org/nl/firefox/addon/restclient/

С помощью REST клиента Вы можете тестировать API, делать запросы, авторизоваться и т.д. и т.п.

В настройках REST клиента сразу пропишите заголовки (headers):

Content-Type: application/json;
Accept: application/json;

т.е. Вы тем самым сообщаете VamShop, что всё Ваше общение с API VamShop будет в формате json.

2. Первый запрос к API VamShop и авторизация с помощью JWT токена.

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

К примеру, получить список всего контента движка VamShop 3 можно сделав GET запрос по адресу http://vamshop-en.loc/api/v1.0/nodes/nodes/index

Если Вы просто выполните этот запрос, то получите сообщение:

{
    "message": "You are not authorized to access that location.",
    "url": "/api/v1.0/nodes/nodes/index",
    "code": 401
}

т.е. у Вас нет доступа к API.

Screenshot from 2018-11-03 00-57-26.png

и это правильно, доступ к API могут иметь только администраторы VamShop, либо пользователи, которым предоставлен доступ к API.

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

К примеру, если Вы установили REST клиент Postman, то указать авторизационный токен можно в разделе Authorization

Слева в опции Type выбираете Bearer Token, затем справа в опции Token указываете Ваш JWT токен.

Screenshot from 2018-11-03 00-57-47.png

и снова отправляете запрос в API кнопкой Send.

Как Вы можете видеть, теперь Вы получили доступ к API, теперь API вернул Ваш все данные, которые есть в движке.

Screenshot from 2018-11-03 00-57-57.png

Всё. Вы авторизованы в API и теперь можете спокойно работать с API VamShop, а именно:

1. Выгружать данные из VamShop.

2. Добавлять данные в VamShop.

3. Редактировать данные в VamShop.

4. Удалять данные из VamShop.

Поделиться сообщением


Ссылка на сообщение
Поделиться на другие сайты
VaM

Добавление записей через API.

Адрес: http://vamshop-en.loc/api/v1.0/nodes/nodes/add

Тип запроса: POST

Заголовки запроса:

Content-Type: application/json
Accept: application/json

Вы должны быть авторизованы как админ, что б запрос прошёл.

Пример тела запроса (данных для создаваемого контента):

{
	"title": "Название страницы",
	"body": "Описание страницы",
	"slug": "page-url",
	"path": "/node/page-url",
	"user_id": 1
}

Ответ от API в случае успешного создания страницы:

{
    "success": true,
    "data": {
        "id": X
    }
}

где X - id номер созданной страницы.

 

Удаление записей через API.

Адрес: http://vamshop-en.loc/api/v1.0/nodes/nodes/delete/X

где X - id номер контента.

Тип запроса: DELETE

Заголовки запроса:

Content-Type: application/json
Accept: application/json

Вы должны быть авторизованы как админ, что б запрос прошёл.

После удаления записи, ответ от API будет:

{
    "success": true,
    "data": []
}

 

 

Поделиться сообщением


Ссылка на сообщение
Поделиться на другие сайты
VaM

Редактирование контента через API.

Адрес: http://vamshop-en.loc/api/v1.0/nodes/nodes/edit/2

где X - id номер редактируемой страницы.

Тип запроса: PUT

Заголовки запроса:

Content-Type: application/json
Accept: application/json

Вы должны быть авторизованы как админ, что б запрос прошёл.

Пример тела запроса (данных для создаваемого контента):

{
        "id": 2,
        "parent_id": null,
        "user_id": 1,
        "title": "EDIT About",
        "slug": "about",
        "body": "<p>EDIT This is an example of a Vamshop page, you could edit this to put information about yourself or your site.</p>",
        "status": 1,
        "mime_type": "",
        "comment_status": 0,
        "comment_count": 0,
        "promote": false,
        "path": "/about",
        "terms": "",
        "sticky": false,
        "lft": 1,
        "rght": 2,
        "visibility_roles": "",
        "type": "page",
        "publish_start": null,
        "publish_end": null,
        "updated": "2009-12-25T22:00:00+00:00",
        "updated_by": null,
        "created": "2009-12-25T22:00:00+00:00",
        "created_by": null,
        "meta": [],
        "taxonomies": [],
        "custom_fields": [],
        "url": {
            "plugin": "Vamshop/Nodes",
            "controller": "Nodes",
            "action": "view",
            "type": "page",
            "slug": "about"
        }
       
}

т.е. мы просто взяли из api описание страницы about и отредактировали название страницы и содержимое страницы.


Ответ от API в случае успешного создания страницы:

{
    "success": true,
    "data": []
}

Теперь если посмотреть в админке страницу about, либо api запросом  получить страницу about, то видно, что наши правки сохранились.

Обратите внимение на title и body.

Вот видно как раз, что добавилось слово EDIT, всё сохранилось успешно, т.е. мы изменили содержимое страницы через API запрос.
 

        {
            "id": 2,
            "parent_id": null,
            "user_id": 1,
            "title": "EDIT About",
            "slug": "about",
            "body": "<p>EDIT This is an example of a Vamshop page, you could edit this to put information about yourself or your site.</p>",
            "excerpt": "",
            "status": 1,
            "mime_type": "",
            "comment_status": 0,
            "comment_count": 0,
            "promote": false,
            "path": "/about",
            "terms": "",
            "sticky": false,
            "lft": 1,
            "rght": 2,
            "visibility_roles": null,
            "type": "page",
            "publish_start": null,
            "publish_end": null,
            "updated": "2009-12-25T22:00:00+00:00",
            "updated_by": 1,
            "created": "2009-12-25T22:00:00+00:00",
            "created_by": null,
            "meta": [],
            "taxonomies": [],
            "custom_fields": [],
            "url": {
                "plugin": "Vamshop/Nodes",
                "controller": "Nodes",
                "action": "view",
                "type": "page",
                "slug": "about"
            }
        }

 

 

 

 

Получение контента с определённым id номером через API.

Адрес: http://vamshop-en.loc/api/v1.0/nodes/nodes/view/7

где X - id номер просматриваемой страницы.

Тип запроса: GET

Заголовки запроса:

Content-Type: application/json
Accept: application/json

Вы должны быть авторизованы как админ, что б запрос прошёл.

Ответ от API с данными страницы:

{
    "success": true,
    "data": {
        "id": 7,
        "parent_id": null,
        "user_id": 1,
        "title": "Название страницы",
        "slug": "page-url",
        "body": "Описание страницы",
        "excerpt": null,
        "status": 1,
        "mime_type": null,
        "comment_status": 1,
        "comment_count": 0,
        "promote": false,
        "path": "/node/page-url",
        "terms": null,
        "sticky": false,
        "lft": 5,
        "rght": 6,
        "visibility_roles": null,
        "type": "node",
        "publish_start": null,
        "publish_end": null,
        "updated": "2018-11-02T19:04:33+00:00",
        "updated_by": 1,
        "created": "2018-11-02T18:54:42+00:00",
        "created_by": null,
        "meta": [],
        "taxonomies": [],
        "custom_fields": [],
        "url": {
            "plugin": "Vamshop/Nodes",
            "controller": "Nodes",
            "action": "view",
            "type": "node",
            "slug": "page-url"
        }
    }
}

 

Просмотр всего контента через API.

Адрес: http://vamshop-en.loc/api/v1.0/nodes/nodes/index

Тип запроса: GET

 

Заголовки запроса:

Content-Type: application/json
Accept: application/json

Вы должны быть авторизованы как админ, что б запрос прошёл.

Пример ответа от API с данными о страницах:

{
    "success": true,
    "data": [
        {
            "id": 3,
            "parent_id": null,
            "user_id": 1,
            "title": "sdfsdfsfsd",
            "slug": "sdfsdfsfsd",
            "body": "sdfsdfs",
            "excerpt": "sdfsdfsfd",
            "status": 0,
            "mime_type": null,
            "comment_status": 2,
            "comment_count": 0,
            "promote": false,
            "path": "/blog/sdfsdfsfsd",
            "terms": null,
            "sticky": false,
            "lft": 1,
            "rght": 2,
            "visibility_roles": null,
            "type": "blog",
            "publish_start": null,
            "publish_end": null,
            "updated": "2018-11-02T18:50:31+00:00",
            "updated_by": 1,
            "created": "2018-11-02T18:50:31+00:00",
            "created_by": 1,
            "meta": [],
            "taxonomies": [],
            "custom_fields": [],
            "url": {
                "plugin": "Vamshop/Nodes",
                "controller": "Nodes",
                "action": "view",
                "type": "blog",
                "slug": "sdfsdfsfsd"
            }
        },
        {
            "id": 6,
            "parent_id": null,
            "user_id": 1,
            "title": "test api",
            "slug": "test-api",
            "body": "desc api",
            "excerpt": null,
            "status": null,
            "mime_type": null,
            "comment_status": 1,
            "comment_count": 0,
            "promote": false,
            "path": "/node/test-api",
            "terms": null,
            "sticky": false,
            "lft": 3,
            "rght": 4,
            "visibility_roles": null,
            "type": "node",
            "publish_start": null,
            "publish_end": null,
            "updated": "2018-11-02T18:52:35+00:00",
            "updated_by": null,
            "created": "2018-11-02T18:52:35+00:00",
            "created_by": null,
            "meta": [],
            "taxonomies": [],
            "custom_fields": [],
            "url": {
                "plugin": "Vamshop/Nodes",
                "controller": "Nodes",
                "action": "view",
                "type": "node",
                "slug": "test-api"
            }
        },
        {
            "id": 7,
            "parent_id": null,
            "user_id": 1,
            "title": "Название страницы",
            "slug": "page-url",
            "body": "Описание страницы",
            "excerpt": null,
            "status": 1,
            "mime_type": null,
            "comment_status": 1,
            "comment_count": 0,
            "promote": false,
            "path": "/node/page-url",
            "terms": null,
            "sticky": false,
            "lft": 5,
            "rght": 6,
            "visibility_roles": null,
            "type": "node",
            "publish_start": null,
            "publish_end": null,
            "updated": "2018-11-02T19:04:33+00:00",
            "updated_by": 1,
            "created": "2018-11-02T18:54:42+00:00",
            "created_by": null,
            "meta": [],
            "taxonomies": [],
            "custom_fields": [],
            "url": {
                "plugin": "Vamshop/Nodes",
                "controller": "Nodes",
                "action": "view",
                "type": "node",
                "slug": "page-url"
            }
        }
    ]
}

 

Поделиться сообщением


Ссылка на сообщение
Поделиться на другие сайты
VaM

API сделан через отдельные контроллеры, что б не смешивать обычные запросы с API запросами.
Для создания API используется CakePHP 3 + CRUD модуль.

Документация по CakePHP модулю CRUD - http://crud.readthedocs.io/en/latest/index.html
Документация по настройке API с помощью модуля CakePHP CRUD - http://crud.readthedocs.io/en/latest/api.html

Примеры lookup запросов:

http://ваш-адрес/api/v1.0/users/users/lookup.json - Список пользователей.

http://ваш-адрес/api/v1.0/users/users/lookup.json?role_id=1 - Список админов (role_id=1)
http://ваш-адрес/api/v1.0/users/users/lookup.json?name=admin - Пользователь с именем admin


http://ваш-адрес/api/v1.0/nodes/nodes/lookup.json - Список контента.

http://ваш-адрес/api/v1.0/nodes/nodes/lookup.json?type=page - Список страниц.
http://ваш-адрес/api/v1.0/nodes/nodes/lookup.json?type=blog - Список блогов.
http://ваш-адрес/api/v1.0/nodes/nodes/lookup.json?title=about - Страница с заголовком about
http://ваш-адрес/api/v1.0/nodes/nodes/lookup.json?slug=about - Страница с url адресом about

API построен на основе CakePHP CRUD - https://github.com/FriendsOfCake/crud

Документация - https://crud.readthedocs.io/en/latest/index.html

+ хорошая статья по настройке CRUD API в CakePHP проектах, в двух частях:

http://www.bravo-kernel.com/2015/04/how-to-build-a-cakephp-3-rest-api-in-minutes/

http://www.bravo-kernel.com/2015/04/how-to-use-a-cakephp-3-rest-api/

Поделиться сообщением


Ссылка на сообщение
Поделиться на другие сайты
VaM

В VamShop 3 по умолчанию реализована авторизация API запросов с помощью JWT (Json Web Tokens).

Вот отличная статья на эту тему - http://www.bravo-kernel.com/2015/04/how-to-add-jwt-authentication-to-a-cakephp-3-rest-api/

Как настроить CakePHP + JWT авторизацию для запросов к API.

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

т.е. админов, проще говоря.

 

В VamShop 3 авторизация доступа к API сделана с помощью JWT токенов, т.е. так как описано в статье, ссылка на которую выше указана.

URL адрес для получения токена: http://vamshop-en.loc/api/v1.0/users/users/token

Тип запроса: POST

Заголовки запроса:

Content-Type: application/json
Accept: application/json

Пример тела запроса:

{
	"username": "логин",
	"password": "пароль"
}

т.е. в теле запроса Вы указываете логин и пароль  пользователя (админа).

Тот же самый логин и пароль, с которыми Вы входите в админку VamShop 3.

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

{
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJWYW1zaG9wIiwic3ViIjoxLCJ1c2VyIjp7InVzZXJuYW1lIjoiYWRtaW4iLCJuYW1lIjoiYWRtaW4iLCJ0aW1lem9uZSI6IlVUQyJ9LCJpYXQiOjE1NDExOTI4OTgsImV4cCI6MTU0MjA1Njk0NX0.ENPEt-CTCjP5ZIW0zj4Vvj5ZzXPkvXgPoMKtN6HeXNg"
  }
}

Если логин и/или пароль неправильный указали, либо у пользователя нет доступа к API, ответ будет следующий:

{
  "message": "Not Found",
  "url": "/api/v1.0/users/users/token",
  "code": 404
}

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

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

Все современные библиотеки типа React, AngulatJS, Vue и т.д. поддерживают авторизацию по JWT токенам.

 

Все токены валидные (действительные), как и написано в статье http://www.bravo-kernel.com/2015/04/how-to-add-jwt-authentication-to-a-cakephp-3-rest-api/

Если токен неправильный, то ответ будет соответствующий от VamShop API:

{
    "message": "Signature verification failed",
    "url": "/api/v1.0/nodes/nodes/index",
    "code": 401
}

Если токен устаревший, то ответ от VamShop API будет соответствующий:

{
    "message": "Expired token",
    "url": "/api/v1.0/nodes/nodes/index",
    "code": 401
}

Если токен устарел, надо получить новый, запросом к API.

Проверить токен, который прислал Вам API можно по адресу: https://jwt.io/

Слева в опции Encoded указываете полученный от API JWT токен.

Внизу напишет Invalid Signature, т.е. токен невалидный, недействительный, но это просто потому что Вы секретный ключ ещё не указали справа.

Справа в опции Verify Signature в input поле your secret указываете Ваш ключ проекта, который можно взять в файле /app/config/core.php

В опции SECURITY_SALT вставляете значение опции SECURITY_SALT и Вы увидите, что Ваш токен валидный (действительный), слева будет написано  Signature Verified

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

Screenshot from 2018-11-03 00-24-21.png

Всё, у Вас валидный, т.е. действительный токен JWT, с помощью которого Вы можете подключаться к API VamShop 3 и работать напрямую с данными движка в формате json, т.е. выгружать, добавлять, редактировать, удалять данные.

Можете создавать приложения для Android, iPhone используя API.

Можете создавать frontend, т.е. новый внешний вид Вашего сайта на популярных сегодня библиотеках React, AngulatJS, Vue.

 

 

 

 

Поделиться сообщением


Ссылка на сообщение
Поделиться на другие сайты

Для публикации сообщений создайте учётную запись или авторизуйтесь

Вы должны быть пользователем, чтобы оставить комментарий

Создать учетную запись

Зарегистрируйте новую учётную запись в нашем сообществе. Это очень просто!

Регистрация нового пользователя

Войти

Уже есть аккаунт? Войти в систему.

Войти
Авторизация