API 结构

为了提供一个统一API的实现方式和使用方式，将会做出一系列实现和使用的规范

身份验证

API 使用基于令牌的身份验证机制。某些终端不需要身份验证。您可以通过 /api/token 取得一个令牌，主要有两种令牌：

  • 密码授权令牌
  • 私人访问令牌

一般情况，后台管理程序推荐使用密码授权令牌。

基本结构

  • Notadd 中实现 API 路由的方式，倾向于传统 Laravel 的实现方式，基于 Controller 调用 API Handler 的方式来实现。
  • Handler 中使用 toResponse 方法返回 ApiResponse 的实例。
  • Handler 主要实现 DataHandler、SetHandler 两种类型的 Handler。
  • ApiResponse 为 \Psr\Http\Message\ResponseInterface 契约的一个实现。
  • ApiResponse 实例所提供的并返回至前端调用的数据主要包含：code、data、message。

所支持的相关API操作

  • /oauth/access 验证是否拥有 API 访问 Token
  • /oauth/access/authorize
  • /oauth/access/token
  • /oauth/authorize
  • /oauth/clients
  • /oauth/refresh

API Handler 示例

  1. namespace Notadd\Foundation\Setting\Controllers;
  3. use Notadd\Foundation\Routing\Abstracts\Controller;
  4. use Notadd\Foundation\Setting\Contracts\SettingsRepository;
  5. use Notadd\Foundation\Setting\Handlers\AllHandler;
  6. use Notadd\Foundation\Setting\Handlers\SetHandler;
  8. /**
  9.  * Class ApiController.
  10.  */
  11. class SettingController extends Controller
  12. {
  13.     /**
  14.      * @var \Notadd\Foundation\Setting\Contracts\SettingsRepository
  15.      */
  16.     protected $settings;
  18.     /**
  19.      * SettingController constructor.
  20.      *
  21.      * @param \Notadd\Foundation\Setting\Contracts\SettingsRepository $settings
  22.      *
  23.      * @throws \Illuminate\Contracts\Container\BindingResolutionException
  24.      */
  25.     public function __construct(SettingsRepository $settings)
  26.     {
  27.         parent::__construct();
  28.         $this->settings = $settings;
  29.     }
  31.     /**
  32.      * TODO: Method  Description
  33.      *
  34.      * @param \Notadd\Foundation\Setting\Handlers\AllHandler $handler
  35.      *
  36.      * @return \Notadd\Foundation\Routing\Responses\ApiResponse
  37.      * @throws \Exception
  38.      */
  39.     public function all(AllHandler $handler)
  40.     {
  41.         $response = $handler->toResponse();
  43.         return $response->generateHttpResponse();
  44.     }
  46.     /**
  47.      * @param \Notadd\Foundation\Setting\Handlers\SetHandler $handler
  48.      *
  49.      * @return \Notadd\Foundation\Routing\Responses\ApiResponse
  50.      * @throws \Exception
  51.      */
  52.     public function set(SetHandler $handler)
  53.     {
  54.         $response = $handler->toResponse();
  56.         return $response->generateHttpResponse();
  57.     }
  58. }
  1. namespace Notadd\Foundation\Setting\Handlers;
  3. use Illuminate\Container\Container;
  4. use Illuminate\Http\Request;
  5. use Illuminate\Translation\Translator;
  6. use Notadd\Foundation\Passport\Abstracts\DataHandler;
  7. use Notadd\Foundation\Setting\Contracts\SettingsRepository;
  9. /**
  10.  * Class SettingHandler.
  11.  */
  12. class AllHandler extends DataHandler
  13. {
  14.     /**
  15.      * @var \Notadd\Foundation\Setting\Contracts\SettingsRepository
  16.      */
  17.     protected $settings;
  19.     /**
  20.      * AllHandler constructor.
  21.      *
  22.      * @param \Illuminate\Container\Container                         $container
  23.      * @param \Illuminate\Http\Request                                $request
  24.      * @param \Notadd\Foundation\Setting\Contracts\SettingsRepository $settings
  25.      * @param \Illuminate\Translation\Translator                      $translator
  26.      */
  27.     public function __construct(
  28.         Container $container,
  29.         Request $request,
  30.         SettingsRepository $settings,
  31.         Translator $translator
  32.     ) {
  33.         parent::__construct($container, $request, $translator);
  34.         $this->settings = $settings;
  35.     }
  37.     /**
  38.      * Http code.
  39.      *
  40.      * @return int
  41.      */
  42.     public function code()
  43.     {
  44.         return 200;
  45.     }
  47.     /**
  48.      * Data for handler.
  49.      *
  50.      * @return array
  51.      */
  52.     public function data()
  53.     {
  54.         return $this->settings->all()->toArray();
  55.     }
  57.     /**
  58.      * Errors for handler.
  59.      *
  60.      * @return array
  61.      */
  62.     public function errors()
  63.     {
  64.         return [
  65.             '获取全局设置失败！',
  66.         ];
  67.     }
  69.     /**
  70.      * Messages for handler.
  71.      *
  72.      * @return array
  73.      */
  74.     public function messages()
  75.     {
  76.         return [
  77.             '获取全局设置成功！',
  78.         ];
  79.     }
  80. }
  1. namespace Notadd\Foundation\Setting\Handlers;
  3. use Illuminate\Container\Container;
  4. use Illuminate\Http\Request;
  5. use Illuminate\Translation\Translator;
  6. use Notadd\Foundation\Passport\Abstracts\SetHandler as AbstractSetHandler;
  7. use Notadd\Foundation\Setting\Contracts\SettingsRepository;
  9. /**
  10.  * Class SetHandler.
  11.  */
  12. class SetHandler extends AbstractSetHandler
  13. {
  14.     /**
  15.      * @var \Notadd\Foundation\Setting\Contracts\SettingsRepository
  16.      */
  17.     protected $settings;
  19.     /**
  20.      * SetHandler constructor.
  21.      *
  22.      * @param \Illuminate\Container\Container $container
  23.      * @param \Illuminate\Http\Request $request
  24.      * @param \Notadd\Foundation\Setting\Contracts\SettingsRepository $settings
  25.      * @param \Illuminate\Translation\Translator $translator
  26.      */
  27.     public function __construct(
  28.         Container $container,
  29.         Request $request,
  30.         SettingsRepository $settings,
  31.         Translator $translator
  32.     ) {
  33.         parent::__construct($container, $request, $translator);
  34.         $this->settings = $settings;
  35.     }
  37.     /**
  38.      * Data for handler.
  39.      *
  40.      * @return array
  41.      */
  42.     public function data()
  43.     {
  44.         return $this->settings->all()->toArray();
  45.     }
  47.     /**
  48.      * Errors for handler.
  49.      *
  50.      * @return array
  51.      */
  52.     public function errors()
  53.     {
  54.         return [
  55.             '修改设置失败！',
  56.         ];
  57.     }
  59.     /**
  60.      * Execute Handler.
  61.      *
  62.      * @return bool
  63.      */
  64.     public function execute()
  65.     {
  66.         $this->settings->set('site.enabled', $this->request->input('enabled'));
  67.         $this->settings->set('site.name', $this->request->input('name'));
  68.         $this->settings->set('site.domain', $this->request->input('domain'));
  69.         $this->settings->set('site.beian', $this->request->input('beian'));
  70.         $this->settings->set('site.company', $this->request->input('company'));
  71.         $this->settings->set('site.copyright', $this->request->input('copyright'));
  72.         $this->settings->set('site.statistics', $this->request->input('statistics'));
  74.         return true;
  75.     }
  77.     /**
  78.      * Messages for handler.
  79.      *
  80.      * @return array
  81.      */
  82.     public function messages()
  83.     {
  84.         return [
  85.             '修改设置成功!',
  86.         ];
  87.     }
  88. }

模块类 API 文档