From abe4ae0352bac8c6b01413c01882469fed5f87c6 Mon Sep 17 00:00:00 2001 From: Dmitry <72506029+HSDChannel@users.noreply.github.com> Date: Tue, 8 Feb 2022 00:22:13 +0700 Subject: [PATCH] README.textile -> README.md (#462) --- VKAPI/README.md | 57 ++++++++++++++++++++++++++++++++++++++++++++ VKAPI/README.textile | 31 ------------------------ 2 files changed, 57 insertions(+), 31 deletions(-) create mode 100644 VKAPI/README.md delete mode 100644 VKAPI/README.textile diff --git a/VKAPI/README.md b/VKAPI/README.md new file mode 100644 index 00000000..b3c85918 --- /dev/null +++ b/VKAPI/README.md @@ -0,0 +1,57 @@ +# VK API Compatability layer for OpenVK + +This directory contains VK api handlers, structures and relared +exceptions. It is still a work-in-progress functionality. +**Note**: requests to api are routed through +openvk.Web.Presenters.VKAPIPresenter, this dir contains only handlers. + +## Implementing API methods + +VK API methods have names like this: `example.test`. To implement a +method like this you will need to create a class `Example` in the +Handlers subdirectory. This class **must** extend VKAPIHandler and be +final. +Next step is to create test method. It **must** have a type hint that is +not void. Everything else is fine, the return value of method will be +authomatically converted to JSON and sent back to client. + +### Parameters + +Method arguments are parameters. To declare a parameter just create an +argument with the same name. You should also provide correct type hints +for them. Type conversion is done automatically if possible. If not +possible error №1 will be returned. +If parameter is not passed by client then router will pass default value +to argument. If there is no default value but argument accepts NULL then +NULL will be passed. If NULL is not acceptable, default value is +undefined and parameter is not passed, API will return missing parameter +error to client. + +### Returning errors + +To return an error, call fail method like this: `$this->fail(5, +"error")` (first argument is error code and second is error message). +You can also throw the exception manually: `throw new +APIErrorException("error", 5)` (class: +openvk.VKAPI.Exceptions.APIErrorException). +If you throw any exception that does not inherit APIErrorException then +API will return error №1 (unknown error) to client. + +### Refering to user + +To get user use `getUser` method: `$this->getUser()`. Keep in mind it +will return NULL if user is undefined (no access\_token passed or it is +invalid/expired or roaming authentification failed). +If you need to check whether user is defined use `userAuthorized`. This +method returns true if user is present and false if not. +If your method can’t work without user context call `requireUser` and it +will automatically return unauthorized error. + +### Working with data + +You can use OpenVK models for that. However, **do not** return them +(either you will leak data or JSON conversion will fail). It is better +to create a response object and return it. It is also a good idea to +define a structure in Structures subdirectory. + +Have a lot of fun diff --git a/VKAPI/README.textile b/VKAPI/README.textile deleted file mode 100644 index f212658d..00000000 --- a/VKAPI/README.textile +++ /dev/null @@ -1,31 +0,0 @@ -h1. VK API Compatability layer for OpenVK - -This directory contains VK api handlers, structures and relared exceptions. It is still a work-in-progress functionality. -**Note**: requests to api are routed through openvk.Web.Presenters.VKAPIPresenter, this dir contains only handlers. - -h2. Implementing API methods - -VK API methods have names like this: @example.test@. To implement a method like this you will need to create a class @Example@ in the Handlers subdirectory. This class **must** extend VKAPIHandler and be final. -Next step is to create %test% method. It **must** have a type hint that is not %void%. Everything else is fine, the return value of method will be authomatically converted to JSON and sent back to client. - -h3. Parameters - -Method arguments are parameters. To declare a parameter just create an argument with the same name. You should also provide correct type hints for them. Type conversion is done automatically if possible. If not possible error №1 will be returned. -If parameter is not passed by client then router will pass default value to argument. If there is no default value but argument accepts NULL then NULL will be passed. If NULL is not acceptable, default value is undefined and parameter is not passed, API will return missing parameter error to client. - -h3. Returning errors - -To return an error, call %fail% method like this: @$this->fail(5, "error")@ (first argument is error code and second is error message). You can also throw the exception manually: @throw new APIErrorException("error", 5)@ (class: openvk.VKAPI.Exceptions.APIErrorException). -If you throw any exception that does not inherit APIErrorException then API will return error №1 (unknown error) to client. - -h3. Refering to user - -To get user use @getUser@ method: @$this->getUser()@. Keep in mind it will return NULL if user is undefined (no access_token passed or it is invalid/expired or roaming authentification failed). -If you need to check whether user is defined use @userAuthorized@. This method returns true if user is present and false if not. -If your method can't work without user context call @requireUser@ and it will automatically return unauthorized error. - -h3. Working with data - -You can use OpenVK models for that. However, **do not** return them (either you will leak data or JSON conversion will fail). It is better to create a response object and return it. It is also a good idea to define a structure in Structures subdirectory. - -Have a lot of fun ^^