Understanding REST APIs

What is a REST API?

A REST API (Representational State Transfer Application Programming Interface) is a software architectural style that defines a set of rules and conventions for building and interacting with web services. It is widely used to create web services that can be accessed and consumed by clients over the internet.

REST APIs are based on the principles of the HTTP protocol, which is the foundation of the World Wide Web. They use standard HTTP methods like GET, POST, PUT, and DELETE to perform operations on resources exposed by the API. These resources can be in various formats, such as JSON (JavaScript Object Notation) or XML (eXtensible Markup Language).

The main purpose of a REST API is to provide a standardized and scalable way for different software systems to communicate and exchange data. Here are some reasons why we need REST APIs:

Client-Server Communication: REST APIs enable communication between client applications (such as web browsers, mobile apps, or other servers) and server-side applications. Clients can send HTTP requests to the API to retrieve or manipulate data stored on the server.

Platform Independence: REST APIs are platform-independent, meaning clients and servers can be developed using different programming languages and technologies as long as they adhere to the common rules and conventions of the REST architecture. We already have seen that we can use nearly any programming language for querying databases, and that is true for writing REST APIs too.

Scalability: REST APIs allow for the separation of concerns between the client and server. This allows each component to be developed, deployed, and scaled independently, making it easier to handle increased traffic or load on either side.

Statelessness: REST APIs are stateless, which means that each request from a client contains all the necessary information to be understood by the server. The server does not need to maintain any session state between requests, simplifying the architecture and making it more scalable.

Resourceful Operations: REST APIs expose resources as URLs (Uniform Resource Locators), and clients can perform various operations on these resources using standard HTTP methods. For example, a client can use a GET request to retrieve data, a POST request to create new data, a PUT request to update existing data, or a DELETE request to remove data.

Integration and Interoperability: REST APIs facilitate integration between different systems and applications. They provide a common language and interface for different software components to communicate and exchange data, allowing for the development of complex and distributed systems.

Creating a small REST API with Python

Now lets build a small REST API with Python. We will use the Flask library for creating this REST API. You can install Flask by running the command pip install Flask.

Now create a new file named api.pywith the following content:

from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello_world():
    return 'Hello, World!'

if __name__ == '__main__':
    app.run()

Execute the command python api.py. After that open a Browser and open the URL http://localhost:5000.

Now let's add another endpoint to our API by adding the following code to our Python script:

@app.route('/site')
def site():
    html_code = '<html><head><title>My Site</title></head><body><h1>Hello, World!</h1></body></html>'
    return html_code

After that you need to restart the API by again running the command python api.py. Visit the URL http://localhost:5000/site. This is what you should see:

The API has just returned a HTML website. I have a little exercise for you now: Change the color of the h1 tag to blue (or another color you like) by modifying the HTML code that is returned by our endpoint. Use the style attribute of the h1 tag.

Querying the database and returning the result as a JSON object

Now we want to do something realy fancy. We want to query our database like we did it in the script we have written before and return the records as a JSON object, so that we can use them in a frontend web application.

Modify your Python script like this:

from flask import Flask, jsonify, request
import psycopg2
import psycopg2.extras

app = Flask(__name__)

# Establish a connection to the PostgreSQL database
conn = psycopg2.connect(
    host="localhost",
    port=5432,
    database="postgres",
    user="postgres",
    password="root"
)

@app.route('/messages')
def data():
    try:
        # Create a cursor to perform database operations
        cur = conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor)

        # Execute the SELECT query
        cur.execute("SELECT * FROM messages")

        # Fetch all rows from the result set
        rows = cur.fetchall()

        # Close the cursor
        cur.close()

        # Return the rows as a JSON response
        return jsonify(rows)

    except (psycopg2.Error, psycopg2.DatabaseError) as error:
        print("Error retrieving data from PostgreSQL:", error)

    return jsonify([])


if __name__ == '__main__':
    app.run()
    conn.close()

Restart the Python app, go to the browser and visit the following URL: http://localhost:5000/messages. This is what you should see:

Isn't that great? We have programmed an interface for our database that can now be used by webapps, mobile apps and any other software.

Writing the same REST API in JavaScript

Earlyer in this script I mentioned that you can use nearly any modern programming language for writing REST APIs. Let's proof that and write the same REST API in JavaScript.

First of all we need to create a new JavaScript project by running the command npm init like we did it before. You can also reuse your old project. Next we need to install some libraries. The first library is express, which is the equivalent to Flask in JavaScript. The second library is pg which we already used before. Run the command npm install express ng to install both libraries in your JavaScript project.

Next create a file named api.js with the following content:

const express = require('express');
const app = express();
const { Pool } = require('pg');

// Database connection configuration
const pool = new Pool({
    user: 'postgres',
    password: 'root',
    host: 'localhost',
    database: 'postgres',
    port: 5432,
});

app.get('/', (req, res) => {
  res.send('Hello, World!');
});

app.get('/site', (req, res) => {
  const htmlCode = '<html><head><title>My Site</title></head><body><h1>Hello, World!</h1></body></html>';
  res.send(htmlCode);
});

app.get('/messages', (req, res) => {
  pool.query('SELECT * FROM messages', (error, result) => {
    if (error) {
      console.error('Error retrieving data from PostgreSQL:', error);
      res.json([]);
    } else {
      res.json(result.rows);
    }
  });
});

app.listen(5000, () => {
  console.log('Server is running on port 3000');
});

Now start this REST API by running the following command: node api.js. This should make the REST API run on port 5000. Make sure you have terminated the Python REST API, otherwise this will cause errors, because only one API can listen to port 5000.

Now again visit http://localhost:5000, http://localhost:5000/site and http://localhost:5000/messages. Can you see any difference between the Python and the JavaScript REST API? Both are indistinguishable from a frontend's point of view.

Querying the API via Python scripts

We also can query REST APIs using programming languages. First let's do that with Python. Create a new file named query.py with the following content:

import requests
import json

url = 'http://localhost:5000/messages'  # Replace with your API endpoint URL

response = requests.get(url)

if response.status_code == 200:
    data = response.json()
    print(json.dumps(data, indent=4))
else:
    print('Error:', response.status_code)

Now start the Python REST API and execute the script by running the command python query.py. Next terminate the Python REST API, start the JavaScript REST API and again run the python script. You should see no difference. This is great, we have written a software that is both written in Python and in JavaScript. Now let's write the API query in JavaScript too.

Create a file named query.js with the following content:

const axios = require('axios');

const url = 'http://localhost:5000/messages'; // Replace with your API endpoint URL

axios.get(url)
  .then(response => {
    console.log(JSON.stringify(response.data, null, 4));
  })
  .catch(error => {
    console.error('Error:', error.message);
  });

Before we can execute the script we need to install the Axios library, which is the equivalent to the requests library in Python by running the command npm install axios.

Now execute the script by running node query.js.

Adding new data to the database via the REST API

Next we need to create an endpoint for adding new records into the database. In python we can to this the following way:

@app.route('/messages', methods=['POST'])
def add_message():
    try:
        # Get the JSON data from the request body
        data = request.get_json()
        print("DATA", data)

        # Create a cursor to perform database operations
        cur = conn.cursor()

        # Execute the INSERT query
        cur.execute("INSERT INTO messages (title, sender, message) VALUES (%s, %s, %s)",
                    (data['title'], data['sender'], data['message']))

        # Commit the transaction
        conn.commit()

        # Close the cursor
        cur.close()

        # Return a success response
        return jsonify({'message': 'Message added successfully'})

    except (psycopg2.Error, psycopg2.DatabaseError) as error:
        print("Error adding message to PostgreSQL:", error)

    # Return an error response
    return jsonify({'message': 'Failed to add message'})

In JavaScript we would do this the following way:

app.post('/messages', (req, res) => {
    const data = req.body;

    const query = 'INSERT INTO messages (sender, title, message) VALUES ($1, $2, $3)';

    pool.query(query, [data.sender, data.title, data.message])
      .then(() => {
        res.json({ message: 'Message added successfully' });
      })
      .catch(error => {
        console.error('Error adding message to PostgreSQL:', error);
        res.status(500).json({ error: 'Failed to add message' });
      });
  });

You also need to modify the creation of the app object in your file. Add the line app.use(express.json()); to your file before the endpoints. This line tells express that it should parse JSON objects utomatically.

Sending a POST request to the API

Now let's use Python and JavaScript again to send a POST request to our API to create a new record in our database table.

In Python you can do it the following way:

import requests
import json

url = 'http://localhost:5000/messages'  # Replace with your API endpoint URL

data = {
    'title': 'Call at 2pm',
    'message': 'We have a call at 3pm',
    'sender': 'Jane'
}

headers = {
    'Content-Type': 'application/json'
}

response = requests.post(url, data=json.dumps(data), headers=headers)

if response.status_code == 200:
    response_data = response.json()
    print(response_data)
else:
    print('Error:', response.status_code)

A JavaScript script that does the same looks like this:

const axios = require('axios');

const url = 'http://localhost:5000/messages'; // Replace with your API endpoint URL

const data = {
  title: 'Call at 2pm',
  message: 'We have a call at 2pm',
  sender: 'Jane'
};

const config = {
  headers: {
    'Content-Type': 'application/json'
  }
};

axios.post(url, data, config)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error('Error:', error.message);
  });

Updating records via the REST API

Now it's time to update a record via the REST API. For updating records we are using PUT requests. In our Flask REST API we can add an endpoint for updating records in the following way:

@app.route('/messages/<int:id>', methods=['PUT'])
def update_message(id):
    try:
        # Get the JSON data from the request body
        data = request.get_json()

        # Create a cursor to perform database operations
        cur = conn.cursor()

        # Execute the UPDATE query
        cur.execute(
            "UPDATE messages SET (title, message, sender) = (%s, %s, %s) WHERE id = %s",
            (data['title'], data['message'], data['sender'], id)
        )

        # Commit the transaction
        conn.commit()

        # Close the cursor
        cur.close()

        # Return a success response
        return jsonify({'message': 'Message updated successfully'})

    except (psycopg2.Error, psycopg2.DatabaseError) as error:
        print("Error updating message in PostgreSQL:", error)

    # Return an error response
    return jsonify({'message': 'Failed to update message'})

In JavaScript the equivalend endpoint would look like this:

app.put('/messages/:id', (req, res) => {
  const id = req.params.id;
  const data = req.body;

  const query = 'UPDATE messages SET (title, message, sender) = ($1, $2, $3) WHERE id = $4';

  pool.query(query, [data.title, data.message, data.sender, id])
    .then(() => {
      res.json({ message: 'Message updated successfully' });
    })
    .catch(error => {
      console.error('Error updating message in PostgreSQL:', error);
      res.status(500).json({ error: 'Failed to update message' });
    });
});

Now let's also write scripts that can query the REST API endpoints. In python this would look like the following way:

import requests
import json

id = 5
url = f"http://localhost:5000/messages/{id}"

data = {
    'title': 'Call is now at 5pm',
    'message': 'Sorry, the call has been rescheduled to 5pm',
    'sender': 'Jane'
}

headers = {
    'Content-Type': 'application/json'
}

response = requests.put(url, data=json.dumps(data), headers=headers)

if response.status_code == 200:
    response_data = response.json()
    print(response_data)
else:
    print('Error:', response.status_code)

The equivalent code in JavaScript would look like this:

const axios = require('axios');

id = 5
const url = `http://localhost:5000/messages/${id}`;

const data = {
  title: 'Call is now at 5pm',
  message: 'Sorry, the call has been rescheduled to 5pm',
  sender: 'Jane'
};

const config = {
  headers: {
    'Content-Type': 'application/json'
  }
};

axios.put(url, data, config)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error('Error:', error.message);
  });

Delete records in the database via DELETE requests

Finally we want to delete existing records in our database. We add an endpoint to our REST API that will perform the SQL query for deleting records.

For our Python REST API the endpoint looks like this:

@app.route('/messages/<int:id>', methods=['DELETE'])
def delete_message(id):
    try:
        # Create a cursor to perform database operations
        cur = conn.cursor()

        # Execute the UPDATE query
        cur.execute(
            "DELETE FROM messages WHERE id = %s",
            (id,)
        )

        # Commit the transaction
        conn.commit()

        # Close the cursor
        cur.close()

        # Return a success response
        return jsonify({'message': 'Message deleted successfully'})

    except (psycopg2.Error, psycopg2.DatabaseError) as error:
        print("Error updating message in PostgreSQL:", error)

    # Return an error response
    return jsonify({'message': 'Failed to update message'})

The equivalent JavaScipt endpoint looks like this:

app.delete('/messages/:id', (req, res) => {
  const id = req.params.id;

  const query = 'DELETE FROM messages WHERE id = $1';

  pool.query(query, [id])
    .then(() => {
      res.json({ message: 'Message deleted successfully' });
    })
    .catch(error => {
      console.error('Error deleting message from PostgreSQL:', error);
      res.status(500).json({ error: 'Failed to delete message' });
    });
});

The Python and JavaScript files that can perform DELETE requests look like this:

Python:

import requests
import json

id = 5
url = f"http://localhost:5000/messages/{id}"

response = requests.delete(url)

if response.status_code == 200:
    response_data = response.json()
    print(response_data)
else:
    print('Error:', response.status_code)

JavaScript:

const axios = require('axios');

id = 5
const url = `http://localhost:5000/messages/${id}`;

axios.delete(url)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error('Error:', error.message);
  });

Introducing a new tool for debugging our API

Now that we have seen how we can create REST APIs using Pthon and JavaScript and have seen how we can query the API using the same languages we can introduce a new tool called Postman. If we want to add more endpoints to our REST API writing scripts for querying and debugging the API is a little bit bulky. That why we introduce Postman.

PreviousThe HTTP Protocol NextSetup Postman

Last updated 2 years ago

hashtagWhat is a REST API?

hashtagCreating a small REST API with Python

hashtagQuerying the database and returning the result as a JSON object

hashtagWriting the same REST API in JavaScript

hashtagQuerying the API via Python scripts

hashtagAdding new data to the database via the REST API

hashtagSending a POST request to the API

hashtagUpdating records via the REST API

hashtagDelete records in the database via DELETE requests

hashtagIntroducing a new tool for debugging our API