API Grace Rules
Transferring the functionality of a website, online store or portal to a mobile application has several advantages for both the owner of the online service and its customers. The owner receives an additional communication channel with his target audience and the ability to personalize advertisements, and the user - a more convenient interface, additional functionality and the ability to receive timely alerts.
About what principles and tools we use to add REST API to projects, read under the cat.
There are many API-oriented frameworks. Especially there are many of them on NodeJS, but in other languages ​​it is enough. However, when the task is to use the existing functionality and project data, then changing its architecture in the root, rewriting everything in another language or framework is irrational. We write on our ZeroEngine framework, which is focused on high-load projects and works on the principle of plug-ins. Briefly, the principle of operation of ZeroEngine can be described as follows: a new “module” can be embedded into any existing one, as well as take control of the issue at the right time.
Required to write REST API for the site. The architecture allows you to implement a router and use the existing functionality in whole or in part.
')
When developing in general and, in particular, API, we try to follow the laws of logic and adhere to semantic names, methods and parameters. Here is a sample list of internal requirements adopted by the ZeroTech team:
The method and URL should clearly describe the function performed by the API method. Strictly speaking, when naming an API method, the request method (GET, POST, PUT, DELETE) is a verb in the sentence, and the address is a “path” from the general to the particular.
For example:
We consciously share image and images so that it is immediately clear what exactly will come in response to the request - an array or a single object.
For the error message, we do not assign our own codes, but use the standard set of HTTP codes. To simplify processing on the side of the application, the code is duplicated in the body of the response and supplemented with a description. We are convinced that supplying the application developer with a long description of all errors is not worth the gain in traffic during debugging.
When the question concerns the readability of the code and its reuse, it is better to use more independent methods. But when developing an API, it’s worth minimizing the number of calls to the server as much as possible. Simply put: the data that in the application should be shown together, must also be given together.
Of course, we are talking about modular functional tests duplication. As in the other cases, we try to use the tools for their intended purpose: with unit tests we cover the modules of the site and the router, and we test the API itself using dredd and the Blueprint API.
For this we use the Blueprint API and the apiary service. First, we describe what we want to get in the end. Next, we think over the structure of the methods, their return values, error variants, and so on. Only after that we write the API. This approach has many advantages, and allows API developers to quickly receive comments from application developers, eliminating duplicate work.
When it comes to mobile applications, remember that not all users install the new version immediately upon exit. Therefore, the interface must be compatible with applications running on older versions of the API. There is nothing difficult in this: the application reports in the header the version it needs, and we, changing the major version, transfer the old version of the method controller to the subfolder with the number of its (old) version.
We use TeamCity, but any CI service, including the cloud one, supports unit and dredd tests, as well as integration with Apiary. With successful testing, we update external test sites and analyze several metrics. These actions allow you to quickly track down the problems encountered and ensure that fresh documentation is always available.
Perhaps you already want to try out the principles we use. So, the network will be another good project more. However, in the process you will inevitably encounter difficulties in integrating unit tests into your project, if no tests have been written for it before.
Do not rush to throw out the code and rewrite it from scratch. If your project allows you to embed a module in the architecture, then you can write such a module that allows for selective testing. You will be able to write new modules through TDD, and gradually cover with tests and old ones.
We do it like this: in the folder of our module we install PHPunit and its dependencies, and in the body of the module we call the modified testRunner:
The output will be in the $ out variable. It remains only to display the result on the screen or in a template.
The module is accessible through the admin panel and looks like this:
As noted above, for prototyping, documenting and testing our API, we use the apiary service and its dredd utility:
APIB syntax looks like this:
Apiary converts all this into a convenient interface with a mock server. Application developers can use it even if the "live" API is not written yet or does not work correctly. You can also use the mock server as a sandbox.
In addition, you can view the test history with the dredd utility, if you, for example, do not have a continuous integration interface.
In conclusion, I would like to once again focus on what is not so important, what tools and techniques you use in the development, as long as there is an understanding of the purpose of their use. Our task as programmers is to ensure that programs do what is required of them as accurately and quickly as possible. All the rest is secondary.
About what principles and tools we use to add REST API to projects, read under the cat.
There are many API-oriented frameworks. Especially there are many of them on NodeJS, but in other languages ​​it is enough. However, when the task is to use the existing functionality and project data, then changing its architecture in the root, rewriting everything in another language or framework is irrational. We write on our ZeroEngine framework, which is focused on high-load projects and works on the principle of plug-ins. Briefly, the principle of operation of ZeroEngine can be described as follows: a new “module” can be embedded into any existing one, as well as take control of the issue at the right time.
We summarize the input data
Required to write REST API for the site. The architecture allows you to implement a router and use the existing functionality in whole or in part.
')
When developing in general and, in particular, API, we try to follow the laws of logic and adhere to semantic names, methods and parameters. Here is a sample list of internal requirements adopted by the ZeroTech team:
ACTION / object / id / method
The method and URL should clearly describe the function performed by the API method. Strictly speaking, when naming an API method, the request method (GET, POST, PUT, DELETE) is a verb in the sentence, and the address is a “path” from the general to the particular.
For example:
- GET / images (“get images”) - returns a list of images;
- POST / image - will publish the image;
- PUT / image / 123 - “put” the transferred value in the image number 123.
We consciously share image and images so that it is immediately clear what exactly will come in response to the request - an array or a single object.
Semantic errors
For the error message, we do not assign our own codes, but use the standard set of HTTP codes. To simplify processing on the side of the application, the code is duplicated in the body of the response and supplemented with a description. We are convinced that supplying the application developer with a long description of all errors is not worth the gain in traffic during debugging.
Less methods - less requests
When the question concerns the readability of the code and its reuse, it is better to use more independent methods. But when developing an API, it’s worth minimizing the number of calls to the server as much as possible. Simply put: the data that in the application should be shown together, must also be given together.
Do not test twice
Of course, we are talking about modular functional tests duplication. As in the other cases, we try to use the tools for their intended purpose: with unit tests we cover the modules of the site and the router, and we test the API itself using dredd and the Blueprint API.
Development through documentation
For this we use the Blueprint API and the apiary service. First, we describe what we want to get in the end. Next, we think over the structure of the methods, their return values, error variants, and so on. Only after that we write the API. This approach has many advantages, and allows API developers to quickly receive comments from application developers, eliminating duplicate work.
Versionality
When it comes to mobile applications, remember that not all users install the new version immediately upon exit. Therefore, the interface must be compatible with applications running on older versions of the API. There is nothing difficult in this: the application reports in the header the version it needs, and we, changing the major version, transfer the old version of the method controller to the subfolder with the number of its (old) version.
Continuous integration
We use TeamCity, but any CI service, including the cloud one, supports unit and dredd tests, as well as integration with Apiary. With successful testing, we update external test sites and analyze several metrics. These actions allow you to quickly track down the problems encountered and ensure that fresh documentation is always available.
Introducing Unit Testing to an Existing Project
Perhaps you already want to try out the principles we use. So, the network will be another good project more. However, in the process you will inevitably encounter difficulties in integrating unit tests into your project, if no tests have been written for it before.
Do not rush to throw out the code and rewrite it from scratch. If your project allows you to embed a module in the architecture, then you can write such a module that allows for selective testing. You will be able to write new modules through TDD, and gradually cover with tests and old ones.
We do it like this: in the folder of our module we install PHPunit and its dependencies, and in the body of the module we call the modified testRunner:
$out = ''; $module = "console"; $testRunner = new PHPUnit_TextUI_TestRunner(); $testPrinter = new ZeroTech_printer($out); $testRunner->setPrinter($testPrinter); $testSuite = new PHPUnit_Framework_TestSuite(); foreach (glob(U_PATH . "/tests/*test.php") as $filename) { $testSuite->addTestFile($filename); } $testRunner->doRun($testSuite, array("verbose" => true)); The output will be in the $ out variable. It remains only to display the result on the screen or in a template.
The module is accessible through the admin panel and looks like this:
Functional tests with dredd
As noted above, for prototyping, documenting and testing our API, we use the apiary service and its dredd utility:
- We describe the functionality in the API Blueprint format (a kind of markdown on steroids): We divide the methods into groups, describe why it is needed; which headers / data format / parameters / attributes the method accepts, which ones are required; what are the limitations; what the method returns; to which it responds with errors; in exactly which format.
- Save to file and run dredd file .apib.
- Repair failed tests, refactorize.
- We unload on apiary.
APIB syntax looks like this:
FORMAT: 1A # Group User ## /user ### GET - [GET] + Response 200 (application/json) + Attributes + first_name: (required, string) - ( ) + last_name: (required, string) - ( ) + dob: 1988-10-01 (required, string) - + sex: 1 (required, number) - (0 - , 1 - ) + city: (required, string) - ### POST - [POST] + Request (application/json) + Attributes + first_name: (required, string) - ( ) + last_name: (required, string) - ( ) + dob: 1988-10-01 (required, string) - + sex: 1 (required, number) - (0 - , 1 - ) + city: (required, string) - + Response 201 { message: “Successfully created”, id: 123 } Apiary converts all this into a convenient interface with a mock server. Application developers can use it even if the "live" API is not written yet or does not work correctly. You can also use the mock server as a sandbox.
In addition, you can view the test history with the dredd utility, if you, for example, do not have a continuous integration interface.
Conclusion
In conclusion, I would like to once again focus on what is not so important, what tools and techniques you use in the development, as long as there is an understanding of the purpose of their use. Our task as programmers is to ensure that programs do what is required of them as accurately and quickly as possible. All the rest is secondary.
Source: https://habr.com/ru/post/333884/
All Articles