Changes for page 3. Власні API методи

Last modified by Ashterix on 2024/05/16 12:35

From version 1.1

edited by Ashterix
on 2024/05/10 11:08

Change comment: There is no comment for this version

To version 3.10

edited by Ashterix
on 2024/05/16 12:35

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

@@ -1,46 +1,47 @@
--{{box cssClass="floatinginfobox" width="400px" title="**Contents**"}}
++{{box cssClass="floatinginfobox" title="**Content**"}}
  {{toc/}}
  {{/box}}
  You can easily add your own API methods to the RPC server.
--To do this, simply create any class in your application that is to become an API Service; this class must implement the interface {{code language="none"}}Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService{{/code}}. This interface does not impose any logic on the class; it is only necessary for Symfony to understand that it should be treated as a service available to the RPC server.
++To do this, you just need to create any class that will become an API Service anywhere in your application. This class must implement the interface {{code language="none"}}Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService{{/code}}. This interface does not impose any logic on the class; it is only necessary for Symfony to understand that it should treat it as a service available to the RPC server.
--Implement any public method in your class and it will automatically be available as an API Service.
++Implement any public method in your class, and it will automatically be available as an API Service.
--(% id="cke_bm_318406S" style="display:none" %) (%%) After following the previous instructions, you will have new methods available in the API. By default, method names consist of {{code language="none"}}<className>.<methodName>{{/code}}.
++(% id="cke_bm_318406S" style="display:none" %) (%%) After following the previous instructions, new methods will already be available in the API. By default, method names are composed of {{code language="none"}}<className>.<methodName>{{/code}}.
  = Naming Classes =
--If needed, you can create multiple classes that will be available as API Services.
--Considering their naming **<className>.<methodName>**, I recommend approaching the choice of method name as a simple indication of what it does, and the class name as the namespace of the API method.
++If necessary, you can create several classes that will be available as API Services.
++Considering their naming {{code language="none"}}<className>.<methodName>{{/code}}, I recommend treating the method name as a simple indication of what it does and the class name as the namespace of the API method.
--{{success}}
--== **Best Practice** ==
++(% class="box successmessage" %)
++(((
++== **Best Practices** ==
--The **//Messenger//** class contains methods **//sendEmail()//**, **sendSms()**; the **CartResolver** class contains methods **//addProduct()//**, **getProducts()**, **calculateDiscount()**.
++The class **//Messenger//** contains methods **//sendEmail()//**, **sendSms()**; the class **CartResolver** contains methods **//addProduct()//**, **getProducts()**, **calculateDiscount()**.
  In the API, the following methods will be available:
--* **//CartResolver.addProduct//**
--* **//CartResolver.getProducts//**
--* **//CartResolver.calculateDiscount//**
--* **//Messenger.sendEmail//**
--* **//Messenger.sendSms//**
++* **CartResolver.addProduct**
++* **CartResolver.getProducts**
++* **CartResolver.calculateDiscount**
++* **Messenger.sendEmail**
++* **Messenger.sendSms**
--Just by looking at the method names, it's clear what your server can do.
++Even just by looking at the method names, it is clear what your server can do.
--This approach allows for the use of identical method names in different classes:
++This approach allows you to use the same method names in different classes:
--* **//ProductService.create//**
--* **//ProductService.getName//**
--* **//UserService.create//**
--* **//UserService.getName//**
--{{/success}}
++* **ProductService.create**
++* **ProductService.getName**
++* **UserService.create**
++* **UserService.getName**
++)))
--= Getting Started =
++= Simple Start =
--The following example demonstrates how easy it is to add your methods to the API.
++The following example should demonstrate the ease of adding your methods to the API.
  (% class="row" %)
  (((
@@ -57,30 +57,28 @@
      public function __construct(
          // connecting some dependencies to retrieve data
      ) {}
--
++
      public function getUserNameByUuid(
          string $userId
--    ): string
--    {
--        // some logic get user info by id
++    ): string {
++        // some logic to get user info by id
          return 'some result';
      }
--
++
      public function sendEmail(
--        string $email,
--        string $text,
++        string $email,
++        string $text,
          string $subject = 'Message without subject'
--    ): bool
--    {
--        // some logic send email
++    ): bool {
++        // some logic to send email
          return true;
      }
  }
  {{/code}}
--To the right is an example of the documentation that the server will generate for this class.
++To the right, you see an example of the documentation that the server will generate for this class.
--Basic information regarding parameter names, their types, and optionality is obtained thanks to {{code language="none"}}ReflectionClass{{/code}}, with the order of method arguments, their typehints being crucial.
++The main information about parameter names, their types, and optionality is obtained thanks to (% class="box code" %)ReflectionClass(%%), with the important points being the order of method arguments and their type hints.
  )))
  (% class="col-xs-12 col-sm-6" %)
@@ -87,47 +87,47 @@
  (((
  {{code language="json" layout="LINENUMBERS" title="== Documentation =="}}
  {
--    "methods": {
--        "ExampleApi.getUserNameByUuid": {
--            "name": "ExampleApi.getUserNameByUuid",
--            "description": "",
--            "parameters": {
--                "userId": {
--                    "type": "string",
--                    "name": "userId",
--                    "description": "",
--                    "optional": false
++  "methods": {
++      "ExampleApi.getUserNameByUuid": {
++          "name": "ExampleApi.getUserNameByUuid",
++          "description": "",
++          "parameters": {
++              "userId": {
++                  "type": "string",
++                  "name": "userId",
++                  "description": "",
++                  "optional": false
                  }
              },
--            "returns": "string",
--            "responseFormat": "string"
++          "returns": "string",
++          "responseFormat": "string"
          },
--        "ExampleApi.sendEmail": {
--            "name": "ExampleApi.sendEmail",
--            "description": "",
--            "parameters": {
--                "email": {
--                    "type": "string",
--                    "name": "email",
--                    "description": "",
--                    "optional": false
++      "ExampleApi.sendEmail": {
++          "name": "ExampleApi.sendEmail",
++          "description": "",
++          "parameters": {
++              "email": {
++                  "type": "string",
++                  "name": "email",
++                  "description": "",
++                  "optional": false
                  },
--                "text": {
--                    "type": "string",
--                    "name": "text",
--                    "description": "",
--                    "optional": false
++              "text": {
++                  "type": "string",
++                  "name": "text",
++                  "description": "",
++                  "optional": false
                  },
--                "subject": {
--                    "type": "string",
--                    "name": "subject",
--                    "description": "",
--                    "optional": true,
--                    "default": "Message without subject"
++              "subject": {
++                  "type": "string",
++                  "name": "subject",
++                  "description": "",
++                  "optional": true,
++                  "default": "Message without subject"
                  }
              },
--            "returns": "boolean",
--            "responseFormat": "boolean"
++          "returns": "boolean",
++          "responseFormat": "boolean"
          }
      }
  }
@@ -145,10 +145,10 @@
  (((
  {{code language="json" layout="LINENUMBERS" title="Request"}}
  {
--    "id": "example_request",
--    "method": "ExampleApi.getUserNameByUuid",
--    "params": {
--        "userId": "1111"
++  "id": "example_request",
++  "method": "ExampleApi.getUserNameByUuid",
++  "params": {
++      "userId": "1111"
      }
  }
  {{/code}}
@@ -158,9 +158,9 @@
  (((
  {{code language="json" layout="LINENUMBERS" title="Response"}}
  {
--    "id": "example_request",
--    "result": "some result",
--    "jsonrpc": "2.0"
++  "id": "example_request",
++  "result": "some result",
++  "jsonrpc": "2.0"
  }
  {{/code}}
  )))
@@ -172,12 +172,12 @@
  (((
  {{code language="json" layout="LINENUMBERS" title="Request"}}
  {
--    "id": "example_request",
--    "method": "ExampleApi.sendEmail",
--    "params": {
--        "email": "user@example.com",
--        "subject": "This is test mail",
--        "text": "Hi! This is test send mail by API"
++  "id": "example_request",
++  "method": "ExampleApi.sendEmail",
++  "params": {
++      "email": "user@example.com",
++      "subject": "This is a test mail",
++      "text": "Hi! This is a test email sent by the API"
      }
  }
  {{/code}}
@@ -187,9 +187,9 @@
  (((
  {{code language="json" layout="LINENUMBERS" title="Response"}}
  {
--    "id": "example_request",
--    "result": true,
--    "jsonrpc": "2.0"
++  "id": "example_request",
++  "result": true,
++  "jsonrpc": "2.0"
  }
  {{/code}}
  )))
@@ -197,14 +197,14 @@
  (% class="box warningmessage" %)
  (((
--To simplify the understanding of the documentation, all subsequent examples will be provided using a single method (//**sendEmail**//).
++To simplify the documentation, all further examples will be provided using a single method (//**sendEmail**//).
  )))
--= Method and Parameter Descriptions =
++= Description of Methods and Parameters =
--The documenter relies on all available data related to the method and its arguments (names, types of input and output data, docblocks). Thus, the descriptions of methods and parameters can be enriched through docblocks.
++The documenter relies on all available data belonging to the method and its arguments (names, input and output data types, docblocks). Thus, the description of methods and parameters can be enriched using docblocks.
--Let's add a description of the method and parameters.
++Let's add a description for the method and its parameters.
  (% class="row" %)
  (((
@@ -213,7 +213,6 @@
  {{code language="php" layout="LINENUMBERS" title="== Code =="}}
  <?php
  // ...
--
      /**
       * A method for sending an email message
       * @param string $email The email address
@@ -222,21 +222,17 @@
       * @return bool
       */
      public function sendEmail(
--        string $email,
--        string $text,
++        string $email,
++        string $text,
          string $subject = 'Message without subject'
--    ): bool
--    {
--        // some logic send email
++    ): bool {
++        // some logic to send email
          return true;
      }
--
  // ...
  {{/code}}
  Note the documentation now displays additional information about the method and its parameters.
--
--
  )))
  (% class="col-xs-12 col-sm-6" %)
@@ -243,33 +243,33 @@
  (((
  {{code language="json" layout="LINENUMBERS" title="== Documentation =="}}
  {
--    "methods": {
--        "ExampleApi.sendEmail": {
--            "name": "ExampleApi.sendEmail",
--            "description": "A method for sending an email message",
--            "parameters": {
--                "email": {
--                    "type": "string",
--                    "name": "email",
--                    "description": "The email address",
--                    "optional": false
++  "methods": {
++      "ExampleApi.sendEmail": {
++          "name": "ExampleApi.sendEmail",
++          "description": "A method for sending an email message",
++          "parameters": {
++              "email": {
++                  "type": "string",
++                  "name": "email",
++                  "description": "The email address",
++                  "optional": false
                  },
--                "text": {
--                    "type": "string",
--                    "name": "text",
--                    "description": "Message body",
--                    "optional": false
++              "text": {
++                  "type": "string",
++                  "name": "text",
++                  "description": "Message body",
++                  "optional": false
                  },
--                "subject": {
--                    "type": "string",
--                    "name": "subject",
--                    "description": "Optional message subject parameter",
--                    "optional": true,
--                    "default": "Message without subject"
++              "subject": {
++                  "type": "string",
++                  "name": "subject",
++                  "description": "Optional message subject parameter",
++                  "optional": true,
++                  "default": "Message without subject"
                  }
              },
--            "returns": "boolean",
--            "responseFormat": "boolean"
++          "returns": "boolean",
++          "responseFormat": "boolean"
          }
      }
  }
@@ -277,18 +277,17 @@
  )))
  )))
--= RPC attributes =
++= RPC Attributes =
--For more flexible configuration of your API methods, JsonRpcBundle uses such a tool as [[php attributes>>https://www.php.net/manual/en/language.attributes.overview.php]].
++For more flexible customization of your API methods, JsonRpcBundle uses [[PHP attributes>>url:https://www.php.net/manual/en/language.attributes.overview.php]].
--With specialized attributes, you can:
++With the help of specialized attributes, you can:
--* Set aliases for methods;
--* Specify the response format for methods (if the response is in the form of an array, an object, or a collection of objects);
--* Set up validation of input parameters;
--* Configure caching of responses.
++* set aliases for methods;
++* specify the response format for methods (if the response is in the form of an array, object, or collection of objects);
++* configure input parameter validation;
++* set up response caching.
--Learn more about these attributes:
++Read more about these attributes:
  {{children/}}
--

Changes for page 3. Власні API методи

Summary

Details

Navigation

Child Pages