This post contains some notes about REST and best practices that I follow to design RESTful APIs, it will focus mainly on Uniform interface constraint.

### REST

REST (REpresentational State Transfer) is an architectural approach to design web services presented by Roy Fielding in 2000 in his dissertation. A RESTful API is an API that satisfies the REST constraints.

### Constraints

1. **Client-server -** Separate client application and server application, It’s about separation of concerns, by doing this we improve portability and scalability because it allows those components to evolve independently.

2. **Stateless -** Each request from a client to server must contain all necessary information, including authentication details, the server cannot store anything about requests, sessions, history, etc.

3. **Cache -** When possible responses data have to be cacheable, clients have the right to reuse responses data later. This will improve efficiency and scalability, the trade-off, however, is that it can decrease reliability if the cached data differs significantly from the data in the server.

4. **Uniform interface -** Define the standards of the API interface and follow it, for example, identification of resources and response messages. If it was decided to pluralize resources name on URI, follow this standard in all URIs, it will improve the readability and maintainability.

5. **Layered system -** The system has to be composed of components in hierarchical layers, each component is only aware of the immediate layer with which they are interacting. For example, a system can have a data layer, cache layer, security layer, etc. And all those layers should not affect the communication between the server and client.

6. **Code-on-demand -** This is the only optional constraint, the server will provide static representations of resources, but when requested it can send executable code.

In this post, I will show some best practices to achieve a uniform interface, the constraints 1 and 2 are pretty straightforward, while the other constraints have many ways to satisfy and cover them is out of the scope of this post. 

### Best practices to design an API uniform interface

REST is not limited to but is frequently applied on web applications and leverages HTTP protocol. A RESTful API will expose your system’s resources via a collection of Uniform Resource Identifiers (URIs). Responses will be in JSON or XML, you can provide both formats if you want, in that case, the client will choose using the content-type header. Once defined the system resources, it's time to choose a resource naming strategy and combine it with HTTP Methods to represent operations on those resources. 

Moreover is wise to define standards for responses: what will be the response body in case of failure? Will it have a message describing the error, only a code for reference, or both? And in case of success, what data of resources will be presented? What HTTP Response Codes will be used in each response? These questions have to be addressed in the API design phase.

Let’s use a music streaming service as an example, among other resources it has Artists, Albums, and tracks, let’s see some practices to define the URIs:

#### Use nouns to represent resource, not actions
	
HTTP Methods will indicate the action.

```js
/** Do **/
api.example.com/artists

/** Don't **/
api.example.com/get-artists
```

#### Pluralize resources

The rationale here is that we are dealing with collections of resources.

```js
/** Do **/
api.example.com/albums

/** Don't **/
api.example.com/album
```

#### Demonstrate the hierarchical relationship between resources

This strategy improves comprehension.

```js
api.example.com/artists/{id}/albums
api.example.com/artists/{id}/albums/{id}/tracks
```

Those URIs indicate that artists have a collection of albums that in turn have a collection of tracks. This is not required, often you will find APIs that don’t use this format, for example:

```js
api.example.com/albums
api.example.com/albums/{id}/tracks
```

You may find APIs that provide both formats. Also note that we are not using trailing forward slash, because it doesn’t add semantic value, for example:

```js
api.example.com/artists/{id}/albums/
```

#### Other tips to improve readability

* Use hyphens ( - ) instead of underscores ( _ )
* Use only lowercase letters
* Don’t use file extensions

#### Use HTTP methods to indicate operations on resources

**Most common HTTP Methods**

* **POST -** Create resources
* **GET -** Read resources
* **PUT -** Update or replace resources
* **PATCH -** Modify resources
* **DELETE -** Delete resource

Examples:

```js
/** Get artists **/
GET http://api.example.com/artists

/** Get a particular artist **/
GET http://api.example.com/artists/{id}

/** Create a track **/
POST http://api.example.com/artists/{id}/albums/{id}/tracks

/** Update an album **/
PUT http://api.example.com/artists/{id}/albums/{id}

/** Delete a track **/
DELETE  http://api.example.com/artists/{id}/albums/{id}/tracks/{id}
```

#### Use appropriate HTTP Response Codes on responses

**Most common HTTP Response Codes**

* **200 OK -** Indicate success
* **201 Created -** Successful creation occurred (via POST or PUT)
* **204 No Content -** Indicate success without a response but, commonly used for DELETE and PUT requests
* **400 Bad Request -** Indicate something is not right with the request, for example, missing information or invalid data.
* **401 Unauthorized -** Indicates invalid authentication credentials.
* **403 Forbidden -** User not authorized to perform the operation
* **404 Not found -** Resource not found
* **405 Method not allowed -** Indicates URL exists, but HTTP method is not applicable
* **500 Internal error -** Indicates the server encountered an error and don’t know how to handle


### Conclusion

Many of those practices described here came from reading about, developing, integrating with, and reading APIs documentations. I think that following them is a good way to create a concise and coherent API interface.

This post just scratched the surface, there other related topics worth taking a look at, such as caching, compression, security, versioning, and a lot more. For a more in-depth study I recommend reading the following:
	

* [Architectural Styles and the Design of Network-based Software Architectures](https://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf)
* [Learn REST](https://www.restapitutorial.com/index.html)
* [RESTful web API design](https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design)
* [REST API Tutorial](https://restfulapi.net/)


Also is useful to look at how other APIs was designed, such as:


* [GitHub API](https://docs.github.com/en/rest/reference)
* [Spotfy API](https://developer.spotify.com/documentation/web-api/reference/)
* [DEV API](https://docs.forem.com/api/)




Some notes about REST and best practices that I follow to design RESTful APIs

Best Practices for REST API interface design

When I read [Clean code by Robert C. Martin](https://amzn.to/30HDbGH), I realized I should have read this book years ago, probably in the first year, I start learning to program, because the book contains techniques to write code that is easy to maintain and understandable (especially by other developers) and also points out some mistakes in the code examples that I made too. However, write clean code requires practicing and I was wondering if among all that techniques there are some that are easy to apply even if you are at the beginning of your journey to becoming a software developer. So I came up with four:

### Meaningful names

The task we frequently do is name things: files, variables, methods, etc. And sometimes is hard to find a good name, to make it easier to use intention-revealing names, so when anyone read it will understand it. 

Take this variable, for example:

```js
let u;
```
Can you tell what the variable **u** stores? Probably not because the name **u** reveals nothing, what about now:
```js
let activeUsers;
```
That’s a better name because we read it and understand the intention to stores active users. 

Another example:
```js
function getUsers() {
	// … some code here
	return users.map( user => user.status === ‘active’)
}
```

When you read the function name you understand that the function return users, but when you look at the implementation you discover that the function returns only the active users, a better name would be **getActiveUsers** because it reveals the full intention of the function.

### Small functions that do one thing

How many times did you come across 100 line functions? Well, I have and some of them were written by me. Chances are that those functions are doing more than one thing, you may ask how I’ll know if a function is small enough? What I do is to give an intention-revealing name to it, and that name will tell me if the function is doing more than one thing, if so, I break the function into other functions that do different tasks, and consequently, the functions will become smaller. 

For instance, imagine a function that receives a list of users as an argument, then for each one validates its data, send an email and save it in a database, the intention-revealing name for this function would be something like:

```js
function validateAndSendEmailAndSaveUsers(users) {

}
```
Now it’s easy to know that function is doing more than one thing, next step is to break it into more single-purpose functions: 
```js
function validateUserData(user) {

}

function sendEmail(email) {

}

function saveUser(user) {

}
```

### Avoid using comments

I know, this one is controversial, there are cases where comments are necessary and there are cases where it's not. I want to focus here on the type of comments used to explain a piece of code, like this one:

```js
// verify if you are eligible for the discount
function check() {

}
```

Usually, this type of comment is a sign that the code is not intelligible, so when this happens, and I did it a lot in the past, you should take the time to analyze the code and see if there is a way to improve its intelligibility. The previous example, personally, I prefer like this:

```js
function isElegibleForDiscount() {

}
```

Try to use code to express yourself instead of comments.

### Single-responsibility classes

Probably you have heard of the single responsibility principle, it’s a principle easy to understand, “a class should have one, and only one, reason to change”, therefore only one responsibility. However, for some reason, we still come across super classes with many attributes and methods. Perhaps some developers think that a system with a few large classes is easier to understand, but is the other way around. 
Take a look at the classes you wrote, identify their responsibilities, then for each one create another class to handle it, you’ll end up with a system, with more classes but smaller than the originals, easier to understand and to maintain. Seriously, have you tried to understand an 800 lines class, maybe you have succeeded but didn’t you wish that class were smaller?

I tried to keep it short, I hope those tips help you in your journey and I really recommend reading the [Clean Code book](https://amzn.to/30HDbGH) to delve deeper into the subject.


Write clean code requires practicing and I was wondering if there are some techniques that is easy to apply even if you are in the beginning of your journey to become a software developer. So I came up with four.

Four clean code techniques I wish I knew years ago

Every morning I have to open, resize and reposition all applications I need to work, so I thought: What if I only had to press a keyboard shortcut that could do that for me...

To make this happen I would need to write a script that will be executed by that shortcut, this script would have to do three tasks: Open applications, wait for it to start, and resize and reposition them.

Before continuing, this was developed and tested on [Pop!_OS 20.04 LTS](https://pop.system76.com/), a Ubuntu-based Linux distro. The source code is [here](https://github.com/ricardo93borges/desktop-bootstrap). I could just use suspend mode, but I use dual boot, so that doesn't always work for me, and exploring other tools to find a solution is way more fun.

This script was written in Python 3.8, I called it **desktop-bootstrap.py**, to open the applications I used the [subprocess module](https://docs.python.org/3/library/subprocess.html). And to resize and reposition I used the command line tool [wmctrl](http://tripie.sweb.cz/utils/wmctrl/). The script accepts arguments, so you can open one application at a time, but it also supports a configuration file to open a set of applications, I'll cover in this article the latter approach.

In each line of the configuration file, you write the application you want to open, the command to open it, size and position, like this:

`<command> <Application name> <X Axios> <Y Axios> <Window width> <Window height>`

An example of a configuration file would be:

```
insomnia insomnia 960 0 960 1080
google-chrome google 0 0 960 1080 https://dev.to/ricardo93borges https://github.com/ricardo93borges
```

Note that most browsers accept as arguments the websites to open when it starts, each website open in a different tab, so we'll take advantage of that. You can name the configuration file as `config-sample.txt`.

Now we need a shell script that will be executed when we use the keyboard shortcut, this shell script will call the python script passing as an argument the location of the configuration file. I want to open a terminal too, so I also included the command to do so in the shell script:

```sh
# desktop-bootstrap.sh

#!/bin/sh
gnome-terminal --geometry 170x25+1920+890 --working-directory=/home
/usr/bin/python3.8 /path/to/desktop-bootstrap.py --file /path/to/config-sample.txt
```

Here is the python script with comments to explain some pieces of the code:

```python
# desktop-bootstrap.py

import subprocess
import time
import sys

"""
I limited the retries, so the script doesn't run 
forever waiting for an application to start 
"""
max_retries = 20

"""
This method get an application ID looking for its name 
in a list obtained by a wmctrl command, 
that ID is used in the resize command
"""
def get_id_by_name(applications_running, name):
    for app in applications_running:
        if app.lower().find(name) > -1:
            return app.split(' ')[0]

"""
This method receives a list of applications and 
for each one check if is running. If is running resize and 
reposition it, if not check again in the next iteration
"""
def resize(applications):
    retry = 0
    while len(applications) > 0:
# Get a list of running applications
        applications_running = subprocess.check_output(["wmctrl", "-lp"]).decode("utf-8").split("\n")
        for index, app in enumerate(applications):
            application_id = get_id_by_name(applications_running, app['name'])
            if application_id:
# Resize and reposition
                dimensions = "-e " f"0,{app['x']},{app['y']},{app['width']},{app['height']}"
                command = ["wmctrl", "-i", "-r", application_id, dimensions]
                subprocess.run(command)
                applications.pop(index)

        retry += 1
        if retry > max_retries:
            break

        time.sleep(5)

"""
This method open the application and send it to 
resize() method to resize and reposition it 
accordingly to the arguments passed
"""
def handle_args():
    command = [sys.argv[1]]

"""
If the application is a browser it may have more 
arguments (the websites to open when it starts)
"""
    for i in range(len(sys.argv) - 7):
        command.append(sys.argv[7 + i])

    output = subprocess.Popen(command)

    applications = [{
        'name': sys.argv[2],
        'pid': output.pid,
        'x': sys.argv[3],
        'y': sys.argv[4],
        'width': sys.argv[5],
        'height': sys.argv[6]
        }]

    resize(applications)

"""
This method handles the configuration file, open 
the applications and send it to resize() method 
to resize and reposition it.
"""
def handle_file(file):
    applications = []
    with open(file) as f:
        for index, line in enumerate(f):
            props = line.split(' ')
            command = [props[0]]

"""
If the application is a browser it may have 
more arguments (the websites to open when it starts)
"""
            for i in range(len(props) - 6):
                command.append(props[6+i])

            output = subprocess.Popen(command)
            applications.append({
                'name': props[1],
                'pid': output.pid,
                'x': props[2],
                'y': props[3],
                'width': props[4],
                'height': props[5]
            })
    resize(applications)

"""
Main method, check the arguments and call the 
appropriated method to process the applications.
"""
def run():
    if len(sys.argv) > 2:
        if sys.argv[1] == "--file":
            handle_file(sys.argv[2])
        else:
            handle_args()
    else:
        print("\nInvalid number of arguments")
        print("\nUse the following arguments: ")
        print("\n<command> <Application name> <X Axios> <Y Axios> <Window width> <Window height>")
        print("\nOr: ")
        print("\n--file <path/to/configuration/file>")

    sys.exit(0)


run()

```

Finally, we'll create the keyboard shortcut, this may differ from one Linux distribution to another, in Pop_OS! 20.04 you open **settings menu** go to **keyboard shortcuts**, then scroll down to the bottom of the list of shortcuts and click on the **+** button. In the window that launched you set a name for the shortcut, in the command input you type the path to that shell script (desktop-bootstrap.sh), for example: `/home/ricardo/workspace/desktop-bootstrap/desktop-bootstrap.sh`. In shortcut, you choose the combinations of keys that will execute the shell script.

And that's it, you can find more details on this [repository](https://github.com/ricardo93borges/desktop-bootstrap).


Every morning I have to open, resize and reposition all applications I need to work, so I thought: What if I only had to press a keyboard shortcut that could do that for me...

Ricardo Borges

Best Practices for REST API interface design

Four clean code techniques I wish I knew years ago

How I open and resize all my applications with just a keyboard shortcut