Documenting, Encrypting, and Unit Testing My First REST API

I added a lot more to my REST API than just the JSON responses. Borum Jot was the first project I tried seriously unit testing my code, encrypting the data, and documenting my back-end. In this article, I will discuss cybersecurity, software testing, and documentation of my REST API.

Encryption

I encrypted my data using defuse/php-encryption. This library, claiming to be secure, unlike other libraries, did the encryption and decryption for me. To encrypt and decrypt, I needed my own key, which I generated by running:

$ composer require defuse/php-encryption
$ vendor/bin/generate-defuse-key

Composer is a package manager for PHP applications. The key is 256 bits long and can be stored either in a file (unsecured) or in the environmental variables. Vercel has a built-in way of storing environmental variables, and was the best place, without extra tools, for me to store the key.

Truthfully, I stored the key in a text file in the

etc

$_ENV

Then, at each request that updated or created data that I wanted to encrypt - task and note details - I loaded the key and called the encryption function. Similarly, for each request that fetched data that I encrypted, I loaded the key and decrypted before sending the response. This way, the front-ends never had to worry about encryption or decryption because I wrote everything on the backend, once.

Documentation

To document my APIs, I got inspiration from the Stack Exchange API documentation. I used NextJS to make a static documentation site for the entire Borum ecosystem, including Borum Jot. Then, for each page, I specified the request method, request headers, query-string, request body (for POST, PUT, and DELETE requests), and response body.

Here is a given page of my developer documentation website, which is live, hosted by Vercel, and open-source on GitHub:

A sample Borum Jot endpoint API reference on my Borum Dev Documentation site

Because I am fluent in JavaScript, I did not have any trouble setting up the documentation site. I have a JSON file with data on each endpoint that I update whenever I update the Borum Jot REST API.

I suggest including the following as a bare minimum when documenting REST or other Web API's:

• Request Headers, if any
• Request Query String
• Request Method
• Request Body
• Response Body

Testing

I used PHPUnit, a PHP unit-testing framework, and GuzzleHttp, a PHP HTTP client, to unit test my application. GuzzleHttp acts as a client to the REST API server, making requests and asserting information about the responses.

namespace BorumJot\Tests;

use PHPUnit\Framework\TestCase;
use GuzzleHttp\Client;

class LoginTest extends TestCase {
    private $http;
    public function setUp() : void {
        $this->http = new Client(["base_uri" => "https://api.jot.bforborum.com/api/v1/"]);
    }
    public function testPost() {
        $response = $this->http->post('login');

        $this->assertEquals(200, $response->getStatusCode());

        $contentType = $response->getHeaders()["Content-Type"][0];
        $this->assertEquals("application/json; charset=UTF-8", $contentType);
    }
}

The TestCase is a superclass in PHPUnit that indicates that the class contains test cases. The

setUp()

Client

.get()

.post()

Setting Up Unit Testing

First I had to run

composer install phpunit/phpunit guzzlehttp/guzzle

I added the following to composer.json into the top-level object.

"scripts": {
   "test": "phpunit tests"
}

This will substitute phpunit tests for composer test. It is a common practice to substitute the unit testing framework command for the package manager's command to have one command prefix to rule them all. However, this is not necessary, for you could simply run phpunit tests.

The last step is to configure phpunit to find the folder with all the unit tests. I put mine in the root directory and called it

tests

<?xml version="1.0" encoding="UTF-8"?>
<phpunit bootstrap="vendor/autoload.php">
    <testsuites>
        <testsuite name="Borum Jot REST API Test Suite">
            <directory suffix=".php">./tests/</directory>
        </testsuite>
    </testsuites>
</phpunit>

Replace

./tests/

And that's how I documented, tested, and encrypted the data of my first REST API. Have you ever documented your own API? What tools did you use? Share your own projects down below!