Introduction

Part 1, Chapter 1

What is a RESTful API?

Put simply, a RESTful API is an API that adheres to REST constraints.

An API, which stands for Application Programming Interface, is an interface for computers instead of people. It's a method of communication between two machines.

REST, which stands for Representational State Transfer, is an architectural style for providing standards between computer systems on the web. Its purpose is to make it easier for systems to communicate with each other.

For a system to be "RESTful" -- i.e., compliant with REST -- it needs to abide by some rules:

1. Separation of Concerns: The client and server are separated
2. Stateless: Each request from the client to the server is stateless. In other words, both the client and server can understand any request independently, without seeing any of the previous requests.
3. Uniformed Interface: All API endpoints should be accessible by the same approach.

The heart of a RESTful API is its resources. When working with Django and Django REST Framework, the resources typically correspond back to the models. In this course, the resource that we'll spend the most time on is "shopping items".

Resources can either be a singleton -- a single shopping item -- or a collection -- multiple shopping items. Resources should be nouns, while the CRUD actions -- e.g., create, read/retrieve, update, or delete -- performed against the resource are verbs.

The URLs/endpoints are also expected to be built around resources. See the table below for details.

Identifying the appropriate resources in your project can be both very intuitive and challenging. Take the time to think about your overall project architecture and the project's end goals before you start coding. A poorly designed RESTful API can be very difficult to use.

The following table shows how the common methods combined with the scope provide different results and how their URLs should be built:

Examples

Here are a few examples of some publicly accessible RESTful APIs:

• http.cat (code)
• CoffeeAPI (code)
• OpenWeatherMap
• NASA
• Open Food Facts

Django REST Framework

Django REST Framework (DRF) is a widely-used, full-featured API framework designed for building RESTful APIs with Django. At its core, DRF integrates with Django's core features -- models, views, and URLs -- making it simple and seamless to create RESTful HTTP resources.

DRF is composed of the following components:

1. Serializers are used to convert Django QuerySets and model instances to (serialization) and from (deserialization) JSON (and a number of other data rendering formats like XML and YAML).
2. Views (along with ViewSets), which are similar to traditional Django views, handle RESTful HTTP requests and responses. The view itself uses the serializers to validate incoming payloads and contains the necessary logic to return the response. Views are coupled with routers, which map the views back to the exposed URLs.

While DRF's documentation is quite comprehensive, it can be difficult to navigate and confusing if you're not used to it. It's broken up between two main parts:

1. API Guide
2. Tutorial

You'll often have to combine the two when trying something new. This course helps to bridge the gap as well.

What Does This Course Cover?

In this course, we'll emulate the real-life development cycle of an application. You'll get to know DRF from the ground up as you work your way from basics to more advanced topics.

Along the way, we'll cover:

1. Views (ModelViewSet, generic views, and APIView class)
2. Serializers (out-of-the-box, custom, and nested)
3. Routers
4. Browsable API
5. Custom actions for a ViewSet
6. Permissions and filtering to control access
7. Throttling
8. Token authentication
9. Pagination
10. Validation
11. Ordering
12. Search functionality
13. API documentation

You'll also learn how to manually test your API and write automated tests, progressing to Test-driven Development (TDD). Towards the end of the course, you'll use Docker and Postgres and deploy your app.

We'll also look at how to consume your API from the front-end. Although you won't be developing the front-end code, it's good for a back-end developer to understand how it's being used. By consuming your API (in the front-end and via automated tests), you'll have a better sense of how to structure the API so that it's friendly to use.

DRF Documentation

DRF documentation is fairly specific, and navigating it can take some getting used to.

It has three main sources of information (as can be found in the navbar):

1. Tutorial
2. API Guide
3. Topics

The API Guide part covers everything that has to do with configuring DRF. The API Guide topics are not grouped, so finding all the possibilities of how to achieve something can be complicated at the beginning. For example, Views, Generic views and ViewSets all have to do with views, but this is not communicated design-wise.

Then, there's the Topics part of the docs, which contains topics that you might find interesting for your API but aren't really part of DRF code.

Unlike the API Guide part, where all possibilities are listed, Topics are written more like mini-tutorials -- i.e., you can do this or that in this or that way. For example, the Documenting your API topic explains how to generate documentation from OpenAPI schemas and how to create self-describing APIs.

In the Tutorial part, you can find an idea of how to do something optimally. For example, your first impulse when working with serializers would probably be to turn to the Serializers section on the API Guide, but Serializer relations provides a different way for serializing data -- the Serialization tutorial covers both. The Tutorial part doesn't cover everything, so we recommend using the tutorials to see what the possibilities are and then research deeper in the API Guide.

To sum it up, you could say that the:

• API Guide tells you how to create an API with DRF
• Topics tell you how to use an API created with DRF
• Tutorial provides you with best practices for working with DRF

What You'll Be Building

To get an idea of how a real-life development process works, we'll work on a single API throughout the course. You'll develop a shopping list API, and as we progress through DRF features, the complexity of the API will grow. The API will go from a simple public shopping list to multiple shopping lists that can be accessed only by specific users. At the end of the course, your API will be live, hosted on Heroku.