DEV Community: JekayinOluwa Olabemiwo

Building an Escrow Smart Contract

JekayinOluwa Olabemiwo — Sun, 28 Apr 2024 21:35:42 +0000

According to Wikipedia, escrow is a contractual agreement between two transacting parties whereby a third party holds the funds and makes the disbursement based on certain agreed conditions. An example is a trust account holding funds in a person's name to pay taxes or insurance fees.

It is the bread and butter of Ethereum smart contracts. When a depositor initiates an escrow transaction, the value (Ether) is held in the escrow contract until the beneficiary has fulfilled an agreed task.

Escrow Contract

This code demonstrates an escrow written in Solidity, the prominent language of the Ethereum Virtual Machine (EVM). The contract is called Escrow in the Escrow.sol file:

contract Escrow{...}

State Variables

Variables hold values that are persistently stored in the blockchain (the Ethereum ledger here). The smart contract in this code defines a depositor of value, a beneficiary of transferred value and an arbiter who alone can approve a transfer transaction. Therefore, they are defined early enough in the contract.

Contract Escrow {
    address public depositor;
    address public beneficiary;
    address public arbiter;
    ...
}

the address data type in Solidity is a 20-byte value representing an Ethereum address. We used it for our variables here since they will be EOAs or smart contracts with an Ethereum address.

Constructor and State Variables Initialization

Here, the state variables are initialized in the constructor of the contract. This is similar to how classes are defined in some object-oriented languages like C#.

contract Escrow {
    ...
    constructor(address _arbiter, address _beneficiary) payable {
        arbiter = _arbiter;
        beneficiary = _beneficiary;
        depositor = msg.sender;
    }
}

In the above code, the depositor deploys the contract and, the msg.sender address assumes the position of the depositor in our escrow contract. The msg.sender is a globally available identifier for the externally owned account (EOA) or another smart contract calling our escrow smart contract. Read more about the use of msg.sender in this metaschool.so answer by Munim Iftikhar.

The depositor being the deployer of the contract obtains the addresses of the arbiter and beneficiary and stores the addresses as arguments to our contract for storage as state variables.

It's noteworthy to point out that the payable keyword in the constructor code above identifies the contract as being able to pay the beneficiary after the arbiter approves the value transfer. The payable keyword is used in Solidity to signify the ability to accept ether. Ether is the denomination of payment for EVM computation.

Arbiter and Transfer Approval

In the following code, we will write the logic to transfer the value in the escrow balance to the beneficiary whose address we saved in the state storage. This is how the arbiter will be able to approve the transfer of the deposit to the beneficiary. Let's create a function approve() for the process:

...

function approve() external {        
    uint balance = address(this).balance;
    (bool success, ) = beneficiary.call{ value: balance }("");
    require(success);
}

the external keyword in the function definition indicates that the approve() function can only be used outside of the contract by other contracts.
address(this).balance allows us to access the constructor's balance with its address using the this keyboard. This is the value in the escrow. In some languages like JavaScript, this keyword helps to access variables defined within a specified scope of usage.
we made a message call to beneficiary transfering the escrow balance to the beneficiary
we used the require(success) line to handle when the approve() function executes successfully

Arbiter Authorization

We need to allow only the arbiter to approve the deposit transfer. Therefore, we will create an Error to be returned once the arbiter is not the approver.

...
error NotAuthorized();

function approve() external {
    if(msg.sender != arbiter) revert NotAuthorized();
    ...
    require(success);
}
...

In the code above:

we specify our custom error titled "NotAuthorized"
In the approve() function, we used the revert keyword to throw NotAuthorized when the msg.sender of the deposit transfer is not the arbiter. The msg.sender signifies the address that is approving the transfer from the escrow to the beneficiary.

Emitting Events

Events are a way to emit data for front-end systems and servers consuming or working with our contract. They can listen to events and get up-to-date information for their users and processes alike. Let us add an event, Approved(uint) which we will use to emit the escrow balance that the arbiter transfers to the beneficiary.

...
event Approved(uint);
...

function approve() external {
    ...
    emit Approved(balance);
}

Conclusion

I hope you enjoyed reading this short tutorial. We have just touched on one of the first concepts in blockchain development. The smart contract source code is on GitHub.

You can go ahead and build other use cases for smart contracts and improve your knowledge of Solidity. The Solidity documentation is a great place to start. You can also learn more about Ethereum development from the Ethereum documentation.

Are there any other concepts you would like me to write about? Share them with me! You can find me on Twitter.

Cover Photo by Mikhail Nilov: https://www.pexels.com/photo/people-having-a-meeting-7731327/

A faster way to learn new languages

JekayinOluwa Olabemiwo — Thu, 25 Apr 2024 23:08:53 +0000

This post is not about tutorials, books, videos, solving random code challenges, learning paths, or roadmaps. It's about a strategy. Stay with me as I show you.

Let's get into it!

Firstly, solve some common data structure problems with it. implement some data structures like arrays, linked lists, stacks, queues, etc. You can check common problems on LeetCode, Hackerank or some other resources.

Then, go into the popularly known key/difficult concepts of the language. In JavaScript, such concepts include scopes & closures, callbacks, destructuring, rest & spread, higher-order functions (the trio of map, reduce, filter), regular expressions, error handling, objects, prototypes, classes, etc. Find common problems within the domain of those concepts and attempt to solve them. You can read about them in MDN, in some articles online, on Wikipedia or in books. You may also explanatory videos on YouTube or elsewhere.

Do I understand these concepts? Yes. Can I read and understand JavaScript & ES6? Yes. Have I mastered them? No, that comes with frequent writing of the language.

However, I'm comfortable with them enough to advance into server programming or browser technology with JavaScript, which are advanced concepts.

One thing I didn’t much spend time on

Asynchronous programming is one of the key JS concepts but I didn't spend much time on it as I believed my understanding of asynchronous programming from Python & C# would carry into my JavaScript usage. Also, I already learnt and understood functions, closures, callbacks, promises & error handling. I can learn generators and other async concepts as I use the language more. Therefore, with more frequent coding in the language, I won’t have much trouble doing async programming.

How long?

It took me 4 days approx to get here. I used the language years back but didn't have a strong foundation in it then unlike now that I'm picking it up again. I knew just barely enough to do side projects with Vue.js since I had always been more focused on the backend with Python.

Note: I have a strong Python foundation and years of experience using Python professionally. Along the line, I've had to use other languages too and learned core computer science concepts like data structures and algorithms.

What’s next?

I can either go the Node.js way as I’m biased towards the B.E or React.js before which I have to learn JS browser & DOM operations. Either way, I will build some projects and maybe write about them too.

Thanks

Thanks for reading up to this point. I hope you find this post nice and insightful. I'll share more about other developer hacks I have found useful in upcoming posts. So, watch out!

If you'd like to share the strategies you have used too in the comment section so I can learn from you. You can find me on Twitter.

Cover photo by Desola Lanre-Ologun on Unsplash

Building a Photo Uploader: A Practical Introduction to the JAMSTACK with Vue.js

JekayinOluwa Olabemiwo — Mon, 18 Oct 2021 22:14:41 +0000

Introduction

JAMSTACK is a JavaScript-powered stack that enables you to harness the powers of JavaScript, APIs, and markups. You can build with the JAMSTACK by using the various JavaScript frameworks and libraries and integrate with serverless functions or APIs. It is fast, lean and inexpensive.

In this tutorial, you will learn how to build JAMSTACK apps with a feature to upload images. You will use Cloudinary to power the upload functionality and Auth0 for authentication. This can come in handy when building photo albums, e-commerce applications, and business websites.

For a brief introduction to Vue.js, you can check out this article, Getting Started with Vue JS: The Progressive JavaScript Framework.

Prerequisites

A machine with Node.js and npm) installed.
Basic familiarity with JavaScript, and ES6 and Vue.js).
A text editor. E.g. Sublime Text, Visual Studio Code, Atom, etc.
A Cloudinary account. You can sign up for a Cloudinary account for free.
An Auth0 account. You may create a free Auth0 account here.

Install the Project Dependencies

You need the Node.js runtime and the npm to use Vue.js. The Node package manager, npm will enable you to use Node.js on the command-line interface, CLI. If you do not have Node.js or npm installed, you can follow the instructions here to install them on your machine.

Another tool that you need to follow in this tutorial is the Vue CLI package. The vue library will provide the capabilities of the Vue.js framework while vue-cli will enable you to use certain terminal commands to interact with Vue.js and your project.

You can go ahead to install Vue and the vue-cli tool if you have Node.js and npm on your machine already. Use the following terminal commands to install the two packages respectively.

npm install vue
npm install -g @vue/cli

In the next section, you will set up your Vue.js project.

Create Vue Project

Use the following vue-cli command to set up a Vue.js project on your terminal. You may name the project vue-photo-uploader.

vue create vue-photo-uploader

Select Vue.js 2 version in the options prompted and allow Vue to scaffold the project folders and files for you. You should get a message that looks like the following in your terminal.


📄 Generating README.md...

🎉 Successfully created project vue-photo-uploader.
👉 Get started with the following commands:

Now, you need to set up the new project to handle file uploads. This is the purpose of the next section of the tutorial.

Configue the Vue.js Project for File Uploads

To handle file uploads, you will need to create an interface for your users to be able to upload files. To do that, modify the App.vue file of your project as follows:

<template>
  <div id="app">
    <div>
      <img alt="Vue logo" src="./assets/logo.png">
      <HelloWorld msg="Learn how to upload photos with Cloudinary"/>
    </div>

    <div>
        <div>
            <button @click="openUploadModel">Add Photo</button>
        </div>
    </div>
  </div>
</template>

In the above code, you edited the message to be displayed by the HelloWorld component. You changed it to learn how to upload photos with Cloudinary. In addition, you created a button that calls the openUploadModel method. The method will open the Cloudinary upload modal when the button is clicked. Now, add the method inside the part of the <code>App.vue</code> file as follows: <div class="highlight"><pre class="highlight javascript"><code><script> import HelloWorld from './components/HelloWorld.vue' export default { name: 'App', components: { HelloWorld, }, methods: { openUploadModel() { } } </script> </code></pre></div> The full code of the <code>App.vue</code> file becomes: <div class="highlight"><pre class="highlight html"><code><template> <div id="app"> <div> <img alt="Vue logo" src="./assets/logo.png"> <HelloWorld msg="Learn how to upload photos with Cloudinary"/> </div> <div> <div> <button @click="openUploadModel">Add Photo</button> </div> </div> </div> </template> <script> import HelloWorld from './components/HelloWorld.vue' export default { name: 'App', components: { HelloWorld, }, methods: { openUploadModal() { } } </script> </code></pre></div> <h2> <a name="configure-cloudinary-upload-widget" href="#configure-cloudinary-upload-widget" class="anchor"> </a> Configure Cloudinary Upload Widget </h2> Login and obtain parameters Login to your Cloudinary account and go to your <a href="https://cloudinary.com/console">console dashboard</a> and get your cloud name. Also, get your upload preset from your Cloudinary <a href="https://cloudinary.com/console/settings/upload">acount settings</a>. Copy the two values somewhere because you will need them in your Vue.js project. Configure Upload Preset settings In your account settings page, scroll down the <a href="https://cloudinary.com/console/settings/upload">Upload Settings tab</a> to the Upload Preset section as shown below. <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/60s7rb5s14yr0pxkmbpl.png" alt="Upload preset settings on Cloudinary dashboard"/> Activate the unsigned uploading feature by clicking the Enable unsigned uploading link. The link should change to Signed as shown below. <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lpf2zbgczlpss84ui4vi.png" alt="Unsigned uploading feature enabled"/> If you don't enable unsigned upload preset, you might get the following error. <div class="highlight"><pre class="highlight shell"><code>Upload preset must be whitelisted for unsigned uploads </code></pre></div> Next, navigate to the <code>index.html</code> page in the <code>public</code> folder of your project. Then, include the Cloudinary widget script inside the <body> tag. <div class="highlight"><pre class="highlight html"><code><body> <script src="https://widget.cloudinary.com/v2.0/global/all.js" type="text/javascript"></script> ... </body> </code></pre></div> Next, modify the <code>openUploadModal</code> of the <code>App.vue</code> file as follows: <div class="highlight"><pre class="highlight javascript"><code> ... openUploadModal() { window.cloudinary.openUploadWidget( { cloud_name: '<CLOUD_NAME>', upload_preset: '<UPLOAD_PRESET>' }, (error, result) => { if (!error && result && result.event === "success") { console.log('Image uploaded..: ', result.info); } }).open(); } </code></pre></div> In the above code, you added the logic of the <code>@click</code> event of the button by which calls the <code>openUploadWidget</code> method that activates the Cloudinary file upload modal. Replace <code>CLOUD_NAME</code> and <code>UPLOAD_PRESET</code> in the above code with the values you got from your Cloudinary account. Next, run the project on your terminal: <div class="highlight"><pre class="highlight shell"><code>npm run serve </code></pre></div> Then, navigate to <code>127.0.0.1:8000</code> on your browser to add images to the application. You should get a page that looks like the following image. <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6tprnqxu0aawccft6yq3.png" alt="Photo album prototype live!"/> Click the <code>Add Photo</code> button and the upload modal will be displayed like the following. <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hludwb2yinpcy9lfr0bw.png" alt="Cloudinary upload widget"/> Now, you can upload your images. <h2> <a name="deliver-and-view-images-with-cloudinary" href="#deliver-and-view-images-with-cloudinary" class="anchor"> </a> Deliver and View Images with Cloudinary </h2> Cloudinary enables the delivery of images to the browser via its Vue.js SDK, <code>cloudinary-vue</code>. Install the library to get started: <div class="highlight"><pre class="highlight shell"><code>npm install cloudinary-vue </code></pre></div> You need the following Cloudinary Vue.js components to achieve the goal of this section of the article. <code>CldContext</code> - this tag helps you to set the parameters that all the child components share. <code>CldImage</code> - the Cloudinary Image tag. It sources images from Cloudinary and makes them available on the browser. <code>CldTransformation</code> - the tag that allows you to describe the transformations that are applied to the images delivered. Next, import the components in the <code><script></code> section of the <code>App.vue</code> file. In addition, add the image <code>url</code> and <code>public_id</code> to the Data property of Vue.js. These two variables will be defined later in the article. <div class="highlight"><pre class="highlight javascript"><code><script> ... import { CldContext, CldImage, CldTransformation } from 'cloudinary-vue' export default { name: 'App', components: { HelloWorld, CldContext, CldImage, CldTransformation }, data() { return { url: '', publicId: '' } }, ... </script> </code></pre></div> Then, apply the imported components in the template code. <div class="highlight"><pre class="highlight vue"><code><template> <div id="app"> ... <div> <cld-context cloudName="CLOUD_NAME"> <div style="display: flex; justify-content: center;"> <cld-image :publicId="publicId" width="250"> <cld-transformation width="200" height="200" gravity="face" crop="thumb" /> </cld-image> <cld-image :publicId="publicId" width="250"> <cld-transformation width="200" height="200" gravity="face" crop="thumb" /> </cld-image> <cld-image :publicId="publicId" width="250"> <cld-transformation width="200" height="200" gravity="face" crop="thumb" /> </cld-image> <cld-image :publicId="publicId" width="250"> <cld-transformation width="200" height="200" gravity="face" crop="thumb" /> </cld-image> <cld-image :publicId="publicId" width="250"> <cld-transformation width="200" height="200" gravity="face" crop="thumb" /> </cld-image> </div> </cld-context> </div> </div> </template> </code></pre></div> Don't forget to replace <code>CLOUD_NAME</code> in the code above with the real value gotten from your dashboard. Whenever you upload an image, Cloudinary assigns a <code>public_id</code> to an image whenever you are uploading one. Therefore, you can use the <code>public_id</code> returned in Cloudinary's JSON response when an image is being uploaded. So, modify the <code>openUploadModal()</code> method to capture the <code>public_id</code> of an uploaded image. <div class="highlight"><pre class="highlight javascript"><code> openUploadModal() { window.cloudinary.openUploadWidget( { cloud_name: 'CLOUD_NAME', upload_preset: 'UPLOAD_PRESET' }, (error, result) => { if (!error && result && result.event === "success") { console.log('Image uploaded..: ', result.info); //add the next 2 lines this.url = result.info.url; this.publicId = result.info.public_id; } }).open(); } </code></pre></div> The full code of the <code>App.vue</code> file is the following: <div class="highlight"><pre class="highlight html"><code><template> <div id="app"> <img alt="Vue logo" src="./assets/logo.png"> <HelloWorld msg="Learn how to upload photos with Cloudinary"/> <div> <button @click="openUploadModel">Add Photo</button> </div> <div> <cld-context cloudName="diiayntjq"> <div style="display: flex; justify-content: center;"> <cld-image :publicId="publicId" width="250"> <cld-transformation width="600" height="600" gravity="face" crop="thumb" /> </cld-image> </div> </cld-context> </div> </div> </template> <script> import HelloWorld from './components/HelloWorld.vue' import { CldContext, CldImage, CldTransformation } from 'cloudinary-vue' export default { name: 'App', components: { HelloWorld, CldContext, CldImage, CldTransformation }, data() { return { url: '', publicId: '' } }, methods: { openUploadModel() { window.cloudinary.openUploadWidget( { cloud_name: 'diiayntjq', upload_preset: 'bi7uln2q' }, (error, result) => { if (!error && result && result.event === "success") { console.log('Image uploaded..: ', result.info); this.url = result.info.url; this.publicId = result.info.public_id; } }).open(); } } } </script> </code></pre></div> <h2> <a name="authenticating-with-auth0" href="#authenticating-with-auth0" class="anchor"> </a> Authenticating with Auth0 </h2> Auth0 allows you to <a href="https://en.wikipedia.org/wiki/Authentication">authenticate</a> and <a href="https://en.wikipedia.org/wiki/Authorization">authorize</a> users. It integrates with several languages and frameworks for building applications. Furthermore, Auth0 proves a <a href="https://auth0.com/docs/login/universal-login">Universal Login</a> page to help with authenticating users. The login page redirects users back to your application after they log in. Create an Auth0 Application To start the authentication setup, log in to your <a href="https://manage.auth0.com/dashboard/">Auth0 dashboard</a> and follow the following steps to create an Auth0 Application. <ol> <li>Click "Applications" in the left sidebar menu. Supply these parameters: <ul> <li>Name: Vue.js Image Uploader</li> <li> Application type as Single Page Applications</li> </ul></li> <li>Click "Create" button to complete the application creation</li> <li>Click on the "Settings" tab of the newly created Application page. Set the following parameters: <ul> <li>Allowed Callback URLs: <code>http://localhost:8080</code></li> <li>Allowed Logout URLs: <code>http://localhost:8080</code></li> <li>Allowed Web Origins: <code>http://localhost:8080</code></li> </ul></li> <li>Scroll down the page and click on the "Save Changes" button to save the settings.</li> </ol> Install Auth0 Install the Client SDK for Auth0 Single-Page Applications: <div class="highlight"><pre class="highlight shell"><code>npm install @auth0/auth0-spa-js </code></pre></div> Since you need to move from one page or link to another in the Vue.js application, you will need the <a href="https://router.vuejs.org/">Vue router</a>. Add it with the following command and choose 'yes' when asked if you'd like to use it in history mode. <div class="highlight"><pre class="highlight shell"><code>vue add router </code></pre></div> Create a new folder inside the <code>src</code> folder and name it <code>auth</code>. Then, create a new file inside the <code>auth</code> folder and name it <code>index.js</code>. Add the following code inside the file. <div class="highlight"><pre class="highlight javascript"><code>import Vue from "vue"; import createAuth0Client from "@auth0/auth0-spa-js"; /** Define a default action to perform after authentication */ const DEFAULT_REDIRECT_CALLBACK = () => window.history.replaceState({}, document.title, window.location.pathname); let instance; /** Returns the current instance of the SDK */ export const getInstance = () => instance; /** Creates an instance of the Auth0 SDK. If one has already been created, it returns that instance */ export const useAuth0 = ({ onRedirectCallback = DEFAULT_REDIRECT_CALLBACK, redirectUri = window.location.origin, ...options }) => { if (instance) return instance; // The 'instance' is simply a Vue object instance = new Vue({ data() { return { loading: true, isAuthenticated: false, user: {}, auth0Client: null, popupOpen: false, error: null }; }, methods: { /** Authenticates the user using a popup window */ async loginWithPopup(options, config) { this.popupOpen = true; try { await this.auth0Client.loginWithPopup(options, config); this.user = await this.auth0Client.getUser(); this.isAuthenticated = await this.auth0Client.isAuthenticated(); this.error = null; } catch (e) { this.error = e; // eslint-disable-next-line console.error(e); } finally { this.popupOpen = false; } this.user = await this.auth0Client.getUser(); this.isAuthenticated = true; }, /** Handles the callback when logging in using a redirect */ async handleRedirectCallback() { this.loading = true; try { await this.auth0Client.handleRedirectCallback(); this.user = await this.auth0Client.getUser(); this.isAuthenticated = true; this.error = null; } catch (e) { this.error = e; } finally { this.loading = false; } }, /** Authenticates the user using the redirect method */ loginWithRedirect(o) { return this.auth0Client.loginWithRedirect(o); }, /** Returns all the claims present in the ID token */ getIdTokenClaims(o) { return this.auth0Client.getIdTokenClaims(o); }, /** Returns the access token. If the token is invalid or missing, a new one is retrieved */ getTokenSilently(o) { return this.auth0Client.getTokenSilently(o); }, /** Gets the access token using a popup window */ getTokenWithPopup(o) { return this.auth0Client.getTokenWithPopup(o); }, /** Logs the user out and removes their session on the authorization server */ logout(o) { return this.auth0Client.logout(o); } }, /** Use this lifecycle method to instantiate the SDK client */ async created() { // Create a new instance of the SDK client using members of the given options object this.auth0Client = await createAuth0Client({ ...options, client_id: options.clientId, redirect_uri: redirectUri }); try { // If the user is returning to the app after authentication.. if ( window.location.search.includes("code=") && window.location.search.includes("state=") ) { // handle the redirect and retrieve tokens const { appState } = await this.auth0Client.handleRedirectCallback(); this.error = null; // Notify subscribers that the redirect callback has happened, passing the appState // (useful for retrieving any pre-authentication state) onRedirectCallback(appState); } } catch (e) { this.error = e; } finally { // Initialize our internal authentication state this.isAuthenticated = await this.auth0Client.isAuthenticated(); this.user = await this.auth0Client.getUser(); this.loading = false; } } }); return instance; }; // Create a simple Vue plugin to expose the wrapper object throughout the application export const Auth0Plugin = { install(Vue, options) { Vue.prototype.$auth = useAuth0(options); } }; </code></pre></div> The options object in the above code is used to pass in the <code>domain</code> and <code>clientId</code> values. Hence, you have to create a JSON file called <code>auth_config.json</code> in the root folder of the Vue.js application and add the following values to it. Obtain the domain and clientId values from the "Settings" tab of the Auth0 Application page and put them in the JSON file like the following. <div class="highlight"><pre class="highlight shell"><code>{ "domain": "YOUR_DOMAIN", "clientId": "YOUR_CLIENT_ID" } </code></pre></div> Next, import the Auth0 plugin and Vue router in the <code>main.js</code> file as shown below. <div class="highlight"><pre class="highlight vue"><code>... import router from './router' // newly added line // Import the Auth0 configuration import { domain, clientId } from "../auth_config.json"; // Import the plugin here import { Auth0Plugin } from "./auth"; // Install the authentication plugin here Vue.use(Auth0Plugin, { domain, clientId, onRedirectCallback: appState => { router.push( appState && appState.targetUrl ? appState.targetUrl : window.location.pathname ); } }); Vue.config.productionTip = false; new Vue({ router, // newly added line render: h => h(App) }).$mount("#app"); </code></pre></div> Configure Log in and Log out follows Edit the App.vue file by adding two buttons for login and log out after the HelloWorld tag in the template code. <div class="highlight"><pre class="highlight vue"><code><template> <div id="app"> ... <div v-if="!$auth.loading">  <button v-if="!$auth.isAuthenticated" @click="login">Log in</button>  <button v-if="$auth.isAuthenticated" @click="logout">Log out</button> </div> ... </div> </template> </code></pre></div> Next, add the login and log out methods in the list of methods inside the <code><script></code> section <div class="highlight"><pre class="highlight javascript"><code>... methods: { // Log the user in login() { this.$auth.loginWithRedirect(); }, // Log the user out logout() { this.$auth.logout({ returnTo: window.location.origin }); }, openUploadModel() { ... </code></pre></div> Now, you have added the login and log-out buttons and can proceed to test the authentication flow. Go to 127.0.0.1:8000 on your web browser. You will see the login button present now as shown below. <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hh9tll1le8dmethhmh2w.png" alt="Login button is visible on the page now"/> When you click the login button, you will be directed to the Auth0 Universal login Page where your users can sign up or log in after which they will be redirected to your application. <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ccm1zbdb75g0w99fyewm.png" alt="Auth0 universal login page activated"/> You can study the <a href="https://auth0.com/blog/complete-guide-to-vue-user-authentication/">The Complete Guide to Vue.js User Authentication with Auth0</a> for a detailed explanation of the Auth0 implementation in Vue.js. <h2> <a name="conclusion" href="#conclusion" class="anchor"> </a> Conclusion </h2> With the knowledge gained, you can try implementing the <a href="https://cloudinary.com/documentation/image_video_and_file_upload">image and video upload</a> in your next project. You may also develop a full-fledged user profile with Auth0. Much more, you can learn about the <a href="https://jamstack.org/">JAMSTACK</a> and its ecosystem as you build more JAMSTACK projects. Thanks for your attention. Content created for the <a href="https://content.hackmamba.io/">Hackmamba</a> Jamstack Content Hackathon using <a href="https://auth0.com/">Auth0</a>, <a href="https://cloudinary.com/">Cloudinary</a> and <a href="https://vuejs.org/">Vue.js</a>.

Django Rest Framework with PostgreSQL: A CRUD Tutorial

JekayinOluwa Olabemiwo — Wed, 24 Feb 2021 17:05:53 +0000

Working with APIs is important for most web developers. From extending other services for your app to providing resources for other apps and services, APIs are essential to modern web systems for application-to-application communication.

API, an acronym for Application Programming Interface is a means by which the client-side interacts with the server-side to respond to the request of the user. It is a protocol that establishes how components of software communicate together.

In this tutorial, we shall go through the procedure of creating a REST API with Django and a PostgreSQL database for a customer management app. We shall set up a Django app with Django Rest Framework. Also, we will install PostgreSQL and connect it with our API. Besides, we shall perform CRUD operations (GET, POST, PUT and DELETE) on the API.

The objective of this tutorial is to create a RESTful API with CRUD capabilities on the database. We shall set up the Django REST framework, create the views and corresponding URL patterns for the APIs and

In detail, we shall go through the following content:

What is Django
What is a RESTful API
What is Django Rest Framework
What are CRUD operations
What is PostgreSQL
Setting up Django Rest Framework
Setting up PostgreSQL
Creating up a Postgres database
Connecting the Postgres database with the API
Creating Views for the CRUD Operations
Creating corresponding URL patterns for the views

Prerequisites

Have Python and pip package manager installed
Have experience creating Django apps
Have basic knowledge of Python programming
Have basic experience using the command line

What is Django?

Django is an open-source Python framework for building high-performance web applications. It works by the Model-View-Controller design. A notable benefit of the framework is that it enables you to build websites with speed without re-inventing the wheel.

What is a REST API?

RESTful API is an architectural standard for APIs that request data using HTTP. The data can be used to create, update, read, and delete resources. REST is an acronym for representational state transfer and, it uses HTTP to request data from a particular URL and, it returns the data in different formats such as JSON, HTML, etc.

What is Django Rest Framework

Django REST framework (DRF) is an extensive and versatile toolkit for building APIs for the web. Not only is it widely used, but it is also very customizable.

What are CRUD operations?

CRUD refers to the four basic operations - Create, Read, Update and Delete - used in relational database systems.

CRUD enables the basic functionalities of creating, reading, updating, and deleting resources in a REST environment. The CRUD operations are usually mapped to standard HTTP methods - POST for creating, GET for reading, PUT for updating, and DELETE for deleting respectively.

From a database management perspective, the following explains how the CRUD operations work.

CREATE: INSERT to create a new database record
READ: SELECT to retrieve data from a database table
UPDATE: UPDATES a record based on the specified primary key
DELETE: DELETES a row in a database table

What is PostgreSQL?

PostgreSQL is a free and open-source relational database system. It provides the developer with extensibility and scalability. It works with a lot of programming languages and all major operating systems such as Windows, macOS, and Linux. We will use PostgreSQL as our database for the CRUD app we will build.

Installing PostgreSQL

You can install PostgreSQL with the following command in the terminal.

sudo apt-get update
sudo apt-get install python-pip python-dev libpq-dev postgresql postgresql-contrib

On macOS, you can install posgresql in the terminal with brew:

brew install postgresql

Now, you may start up postresql after its installation with the following command.

brew services start postgresql

If you use a Windows machine, you can download a compatible PostgreSQL installer from the official website of PostgreSQL.

Creating a Database

As part of the installation, PostgreSQL already created a user, postgres by default for carrying out administrative responsibilities. We shall change to the user to create our database and new user.

sudo su - postgres

psql gives us access to the Postgres interactive terminal where we can use the PostgreSQL queries.

psql

Now, we shall create a database for this project. Always make sure to create a separate database for each project you work on.

CREATE DATABASE mydb;

In the above command, we have used the CREATE command in SQL to create our database which we named mydb. We also ended the line with a semi-colon which comes after every command in SQL.

Creating a Database User

Now, we shall create a database user for our database. We will call the user myuser. Replace password with a strong password below.

CREATE USER myuser WITH PASSWORD 'password';

Let us now grant access rights to our new user to enable it to work on the database.

GRANT ALL PRIVILEGES ON DATABASE mydb TO myuser;

We can then exit the current user's shell session and get back to the postgres user's session

\q

Now, let us leave the PostgreSQL interactive terminal back to the terminal.

exit

Installing Django and Setting up a Django Project

When working with Django apps, always create new Django projects in isolated environments with virtual environment packages like virtualenv. Virtual environments help us to work with different versions of Python and other packages with different projects we have on our machine. Let us get the virtualenv package which we shall use to create our virtual environment

sudo pip install virtualenv

Then, let us create a folder to house our projects and change directory into the new folder.

mkdir myproject && cd myproject

Inside the new folder, we will create the virtual environment for our project.

virtualenv env

The above command provides us a duplicate of Python and some other libraries in an isolated environment.

We will activate the virtual environment so we can use it in our project.

source env/bin/activate

The terminal should look like below. The name of the virtual environment will be in brackets preceding the line to show that the virtual environment has been activated.

(env) user@host:_

Going forward, we will install Django and set up our Django app inside the virtual environment.

pip install django djangorestframework psycopg2

We installed the following packages:

Django: the Django package that allows us to work with the Django framework and create Django apps
Django Rest Framework: this toolkit gives us the features to create and use RESTful APIs with Django
psycopg2: PostgreSQL package that connects our app to PostgreSQL

Now, we shall create a Django project with the django-admin command.

django-admin startproject crm_project

cd into the crm-project directory and cd into the sub-directory, crm-project. We need to add the rest_framework into the settings.py file so it will be active in our project. Let us add it inside the INSTALLED_APPS list:

INSTALLED_APPS = [
   ...
    'rest_framework', #new
]

Setting up Django Database Configuration

We have created a PostgreSQL database and a Django project. Now, we shall configure our Django project to use the PostgreSQL database.

Inside the settings.py file of the project, you will see the DATABASES section. It looks like the following:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
    }
}

We need to change the SQLite database configuration to the PostgreSQL database that we created. Therefore, replace the DATABASES code with the following:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql_psycopg2',
        'NAME': 'myproject',
        'USER': 'myuser',
        'PASSWORD': 'password',
        'HOST': 'localhost',
        'PORT': '',
    }
}

Creating a Django app

Let us create an app in our Django project using manage.py file in the root directory of the project. It allows us to work with Django in various ways such as creating apps, creating database tables from models, running the inbuilt server, etc. Whenever you want to run the manage.py file, ensure that you are at the root directory where manage.py exists,

python manage.py startapp customer

If you check the directory, a new sub-directory, customer has been created. Let us add the new customer app to the INSTALLED_APPS list in the settings.py file of our crm-project.

INSTALLED_APPS = [
   ...
    'rest_framework',
    'customer', #new
]

If you cd into customer, you would see that it has its models.py and views.py files.

We shall create models for the customer app. Open the models.py file of the customer app, replace the content in it with the following code.

from django.db import models

class Customer(models.Model):
    name = models.CharField("Name", max_length=240)
    email = models.EmailField()
    created = models.DateField(auto_now_add=True)

    def __str__(self):
        return self.name

The Customer class in the above code extends from Django's Model class. CharField, EmailField ,and DateField are appropriate data types for the respective fields.

At this point, we will create database columns with the fields of our models through the process of migration. We will use the manage.py file to apply the migrations.

python manage.py makemigrations

Then,

python manage.py migrate

Creating a REST API with Django Rest Framework

We shall build our API on Django Rest Framework. We shall be dealing with views, serializers, and URL endpoints. The endpoints are attached to the views which fetch the responses to web requests.

Serializers help with translating between JSON, XML, and native Python objects. Create a new file in the customer directory and name it serializers.py. Input the following code into it.

from rest_framework import serializers
from .models import Customer

class CustomerSerializer(serializers.ModelSerializer):

    class Meta:
        model = Customer 
        fields = ['pk', 'name', 'email', 'created']

The ModelSerializer in the code above helps to serialize data for Customer objects.

Now, we shall extend the GenericAPIViews that come shipped with Django Rest Framework to create our views. Add the following code inside the views.py of the customer app.

...
from django.shortcuts import render
from .models import Customer
from rest_framework import generics
from .serializers import CustomerSerializer


class CustomerCreate(generics.CreateAPIView):
    # API endpoint that allows creation of a new customer
    queryset = Customer.objects.all(),
    serializer_class = CustomerSerializer


class CustomerList(generics.ListAPIView):
    # API endpoint that allows customer to be viewed.
    queryset = Customer.objects.all()
    serializer_class = CustomerSerializer

The above code enables us to use the CustomerCreate view to create a new customer object, and the CustomerList view will be used to list all the customers in the database.

Should in case we want to check for a single customer, we can add a CustomerDetail view as follows:

...
class CustomerDetail(generics.RetrieveAPIView):
    # API endpoint that returns a single customer by pk.
    queryset = Customer.objects.all()
    serializer_class = CustomerSerializer

We will include a view for the Update action,

...
class CustomerUpdate(generics.RetrieveUpdateAPIView):
    # API endpoint that allows a customer record to be updated.
    queryset = Customer.objects.all()
    serializer_class = CustomerSerializer

Let us add a view for the DELETE operation,

...
class CustomerDelete(generics.RetrieveDestroyAPIView):
    # API endpoint that allows a customer record to be deleted.
    queryset = Customer.objects.all()
    serializer_class = CustomerSerializer

Now, create a new urls.py file in the customer directory and add the following code to it.

from django.urls import include, path
from .views import CustomerCreate, CustomerList, CustomerDetail, CustomerUpdate, CustomerDelete


urlpatterns = [
    path('create/', CustomerCreate.as_view(), name='create-customer'),
    path('', CustomerList.as_view()),
    path('<int:pk>/', CustomerDetail.as_view(), name='retrieve-customer'),
    path('update/<int:pk>/', CustomerUpdate.as_view(), name='update-customer'),
    # path('delete/<int:pk>/', CustomerDelete.as_view(), name='delete-customer')
]

Each of the endpoints handles a particular HTTP method. The first endpoint handles the POST method for CREATE operation. The second and third endpoints handle the GET method for READ operations. The fourth endpoint handles the PUT method for UPDATE operation while the last endpoint handles the DELETE operation.

Notwithstanding, we still need to point the root urls.py file to the urls.py file of the customer app. Let us go back to the crm_project sub-directory and open the urls.py file there. We will then include the customer app endpoints.

from django.contrib import admin
from django.urls import path, include #new

urlpatterns = [
    path('admin/', admin.site.urls),
    path('customer/', include('customer.urls')), #new
]

The file already contained the urlpattern for the Django-admin app which gives us administrator capabilities.

Django ships with an inbuilt server that could be used for testing purposes. We will run our application now through the server with the following command:

python manage.py runserver

Let us go to the URL http://127.0.0.1:8000/customer on the browser and we shall the interface of the Browsable API. Browsable API comes with REST Framework and allows us to interact with our API in the absence of a client-side app. We can visit each of the routes earlier defined in the urlpatterns of our customer app and perform the CRUD operations.

The Browsable API looks like the following for the customer-create endpoint at http://127.0.0.1:8000/customer/create

Conclusion

Well-done! We have learned how to set up a Rest API with Django connected to a PostgreSQL database. You can get the full code of the tutorial project here.

This tutorial helped us to build a RESTful API with the Django REST framework. We also learned how to set up PostgreSQL for a Django project. We used the command-line to create PostgreSQL databases and users. We connected the PostgreSQL database to a basic Django customer management application and added CRUD functionalities to the API.

With what we have learned, we should be able to create APIs in our web projects. We would also be able to learn more about API development. Thanks for your time. Kindly ask questions and share your ideas and suggestions.

Twitter | LinkedIn

Django Rest Framework Authentication with Dj-Rest-Auth

JekayinOluwa Olabemiwo — Mon, 22 Feb 2021 20:44:34 +0000

Authentication and authorization in Django RESTful APIs using Dj-Rest-Auth with Gmail server for sending verification emails to users.

Introduction

Oftentimes, we come across websites and apps that demand that we register, that is, sign-up as users for us to have access to some service or feature on those websites and apps. Registering enables us to create accounts. We also get some personal credentials that allow us to have access every time we log in to use the apps. The credentials could consist of a password, email address, and/or username. 3rd-party services such as email accounts and social accounts could be used to create automatic sign-ups. When every we request to sign in to use such websites and apps, we are made to undergo an authentication process whereby the login credentials are checked with registered credentials.

A common concept usually discussed with authentication is authorization. The authorization merely is granting access to specific features or services before or after authentication. In the Django framework, developers might mandate authentication before users can access some services. They can also permit users to access certain services in a web application without authentication. Nonetheless, they can also allow some users to be superusers with certain administrative capabilities.

APIs are used on websites to provide responses to requests from other web services. We could ensure that users who make requests to our APIs are authenticated before they can use the features on our APIs.

In this article, you will learn how to implement authentication with dj-rest-auth in a Django REST framework API for a basic student management website. By using dj-rest-auth, you will be able to add an authentication feature to your Django REST API in few simple lines of code. You will get Sign up, Sign in and Sign out, password change and password reset features. By the end of the article, you will be able to add authentication to Django REST APIs using dj-rest-auth.

Some technologies we would use include:

Django: Django is an open-source Python framework used for web development. It follows the model view controller (MVC) pattern.
Django REST framework: a robust and customizable toolkit for creating RESTful APIs in Django.
Dj-Rest-Auth: a free and open-source package used for handling authentication in Django REST APIs

Outline

Introduction
Prerequisites
Step 1 — Creating Virtual Environment and Setting up Dependencies
Step 2 -Setting up the Django Project and Django REST Framework
Step 3 — Setting up the Student API
Step 4 — Creating Authentication URLs
Step 5 — Testing Authentication with the Browsable API
Conclusion

Prerequisites

A development machine running either Linux, Windows, or macOS
Have Python 3.4 or a later version, and pip installed. You can follow this article, Python 3 Installation & Setup Guide to install and setup Python.
Have a basic experience using the Django framework

Step 1 — Creating Virtual Environment and Setting up Dependencies

We shall start off by setting up a virtual environment and installing the dependencies for our application. A virtual environment will isolate the current project from other projects on our machine. So, we can have distinct versions of Python, pip, and other modules for the current project. If you use a Windows machine, you can learn how to set up virtualenv on Windows in this article, Setting up a Virtual Environment for your Django Project . You can check How to set up virtual environments for Python on a Mac if you run macOS. If you are running an Ubuntu machine, you may want to read How to Set Up a Python Virtual Environment on Ubuntu 20.04. Navigate to your home directory on the terminal. Then, create a virtual environment using the virtualenv package:

cd ~
virtualenv venv

Activate the created virtual environment using source:

source env/bin/activate

Make sure you are in your activated virtual environment while you are working on this project.

Next, you can install the dependencies using pip. These include the following:

Django: web framework to be used for the project.
Django REST framework: package for creating REST APIs with Django.

Install the dependencies with the following command:

pip install django djangorestframework

With the project dependencies installed, you will create the Django project.

Step 2 — Setting up the Django Project and Django REST Framework

Firstly, let us install the tree package. tree is a good tool for viewing files and directory structures from the terminal. We can use it to view the directory structure of our project files.

sudo apt-get install tree

Then, we will create a new Django project by using the django-admin utility on the command-line with the startproject command as follows.

django-admin startproject drfauthproject

Change directory to drfauthproject folder and view the folder with the tree command.

cd ~/drfauthproject/
tree

You should see the terminal output as:

├── drfauthproject
    │   ├── __init__.py
    │   ├── settings.py
    │   ├── urls.py
    │   └── wsgi.py
    └── manage.py

The root folder contains the following essential files:

manage.py: this is a utility script that allows us to create new applications, migrate databases, and other administrative duties.
settings.py: the configuration file that holds the settings for our project. We can edit the settings such as adding newly installed apps to the INSTALLED_APPS settings. You can get more information from the Django documentation on Django settings.
urls.py: a file where we will define our URL patterns and their associated views. The patterns connect the URLS with their respective view functions. You can learn more about views in this tutorial, Django View

Let us add rest_framework, rest_framework.authtoken, which allows the use of token authentication, to the INSTALLED_APPS setting in the settings.py file.

...
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
    'rest_framework.authtoken',
]
...

Save the file after modifying it.

We will then create a new app called students with the manage.py script and the startapp command for creating new apps inside a Django project. The students app will be a module for managing students in our project.

python manage.py startapp students

Navigate to the students directory and use the tree command.

cd students
tree

The output will be like this:

├── __init__.py
   ├── admin.py
   ├── apps.py
   ├── models.py
   ├── tests.py
   └── views.py

The models.py will contain the models which define the database fields of our apps while the views.py file will contain views for receiving and responding to web requests. Let us then add the new app to the INSTALLED_APPS setting in the settings.py file.

...
INSTALLED_APPS = [
    ...
    'rest_framework',
    'rest_framework.authtoken',
    'students'
]
...

Next, we need to perform migrations on the database. In Django, migrations are carried out to persist the changes made in models into the database. The changes include adding and removing models and fields.

python manage.py migrate

The out on the terminal should be like the following:

Operations to perform:
  Apply all migrations: admin, auth, authtoken, contenttypes, sessions
Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying auth.0001_initial... OK
  Applying admin.0001_initial... OK
  Applying admin.0002_logentry_remove_auto_add... OK
  Applying admin.0003_logentry_add_action_flag_choices... OK
  Applying contenttypes.0002_remove_content_type_name... OK
  Applying auth.0002_alter_permission_name_max_length... OK
  Applying auth.0003_alter_user_email_max_length... OK
  Applying auth.0004_alter_user_username_opts... OK
  Applying auth.0005_alter_user_last_login_null... OK
  Applying auth.0006_require_contenttypes_0002... OK
  Applying auth.0007_alter_validators_add_error_messages... OK
  Applying auth.0008_alter_user_username_max_length... OK
  Applying auth.0009_alter_user_last_name_max_length... OK
  Applying auth.0010_alter_group_name_max_length... OK
  Applying auth.0011_update_proxy_permissions... OK
  Applying auth.0012_alter_user_first_name_max_length... OK
  Applying authtoken.0001_initial... OK
  Applying authtoken.0002_auto_20160226_1747... OK
  Applying authtoken.0003_tokenproxy... OK
  Applying sessions.0001_initial... OK

Django comes shipped with a local development server. Let us start the server with the following command.

python manage.py runserver

The output should look like the following

Performing system checks...

System check identified no issues (0 silenced).
October 22, 2018 - 15:14:50
Django version 2.1.2, using settings 'drfauthproject.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Next, on your web browser, navigate to https://127.0.0.1:8000 where the web application will be running from. You will see the following page:

You can stop the development server on the terminal with the Ctrl + C keyboard shortcut or open a new terminal to continue working on the project.

Step 3 — Setting up Student API

Next, we will use the Django REST Framework to create the REST API. We will create the models for database fields. We will also create API view functions for managing the API requests. We will then add API endpoints where the website visitors can access the API. We will also create serializers to transform model instances and QuerySets into JSON format when API responses are served.

When visitors make requests through the endpoints, Django calls the corresponding view to deal with the requests and provide responses to the requests respectively.

Our API endpoints will include the following:

api/students: this endpoint is used to create students and return a list of students.
api/students/<pk:id>: this endpoint is used to get, update, and delete single students by id or primary key.

Creating the Student Model

The Student model represents the database table that will contain the students’ data. The Django Object Relational Mapper (ORM) handles database management for us by providing a Python interface for SQL operations. It maps the Python classes and variables in our models to corresponding SQL tables and columns. Hence we do not need to use SQL queries ourselves.

Navigate into the directory and open the models.py file inside with the nano command. You can learn more about GNU nano text editor for Unix-like systems from this How to Use Nano, the Linux Command Line Text Editor

cd ~/drfauthproject/students/
nano models.py

You will see that it contains the following lines:

from django.db import models
# Create your models here.

from django.db import models already imports the Student model's API for us. Let us now add the Student class with the following fields:

first_name: the first name of the studentlast_name: the last name of the student
email: the email address of the student
classroom: the classroom the student is in

Add the code for the Student model :

from django.db import models

class Student(models.Model):
    first_name = models.CharField("First name", max_length=255)
    last_name = models.CharField("Last name", max_length=255)
    email = models.EmailField()
    classroom = models.CharField("Classroom", max_length=20)

    def __str__(self):
        return self.first_name

In the code above, the Student class extends the models. Model from django.db.models.Model. The str() function tells how the model will be displaced. Here, we specified with a return statement that the student's first name should be displayed. You can learn more about Django Models in this article, how to write Django models.

Now, we will migrate the database to create tables. We will use the makemigrations command to create migration files where the model changes are reflected. The changes will then be applied to the database with the migrate command. So, let's navigate back to the root directory of the project where we can use our manage.py utility script.

cd ~/drfauthproject

Then, let us create the migration files:

python manage.py makemigrations

The output on the terminal will look like the following:

students/migrations/0001_initial.py
    - Create model Student

Then, apply the changes to the database:

python manage.py migrate

If the migration completes, the output will show as below:

Operations to perform:
  Apply all migrations: admin, auth, contenttypes, sessions, students
Running migrations:
  Applying customers.0001_initial... OK

Create the Serializer Class

We shall add a serializer class for the Student model. The serializer class will convert student instances and QuerySets to and from JSON. Let us start off by creating a serilizers.py file inside the students application directory.

Navigate to the students folder and create make the serializers.py file using the command nano:

cd ~/drfauthproject/students/
nano serializers.py

Add the following lines of code to the file:

from rest_framework import serializers
from .models import Student


class StudentSerializer(serializers.ModelSerializer):

    class Meta:
        model = Student
        fields = ('pk', 'first_name', 'last_name', 'email', 'classroom')

From the first two lines, we imported the serializers API from the Django REST framework and the Student model from the models.py file of the student application. We then created the CustomerSerializer class which extends the serializers.ModelSerializer to specify the specific fields to be serialized.

We then used the Meta class to define the model and fields to be serialized which are: pk, first_name, last_name, email, and class.

Now that we have created the serializer class for the Student model, we shall create the API views.

Making the API Views

At this point, we want to add the API views for the Student application. Whenever an endpoint is visited, Django will fetch the corresponding view.

Open the views.py file in the students application directory and replace what is there with the following code:

from .models import Student
from rest_framework.generics import ListCreateAPIView,  RetrieveUpdateDestroyAPIView
from rest_framework.permissions import IsAuthenticated
from .serializers import StudentSerializer

With the above code, we imported the following:

the Student model from the models.py file of the Student application.
the generic view from the Django REST Framework. You can read more about other generic views provided by the Django REST Framework in this article, Generic views
the IsAuthenticated permission class from the permissions module of the Django REST Framework to authorize user access to our own views. This ensures that the user is authenticated before they are able to perform a particular action or access a resource.
the StudentSerializer class from the serializers.py file of the Student application

Next, let us add our API views:

...
class StudentList(ListCreateAPIView):
    permission_classes = [IsAuthenticated]
    queryset = Student.objects.all()
    serializer_class = StudentSerializer

class StudentDetail(RetrieveUpdateDestroyAPIView):
    permission_classes = [IsAuthenticated]
    queryset = Student.objects.all()
    serializer_class = StudentSerializer

In the above code, we created 2 classes — StudentList and StudentDetail.

StudentList enables us to accept GET requests to list all the students available. It also allows us to accept POST requests to create a new student.
StudentDetail responds to GET requests to provide the details of a specific student as indicated by the id or primary_key. It also responds to PUT requests to update one or more of the fields of a student. It also deletes a student instance when a DELETE request is made.

However, permission_classes = [IsAuthenticated] ensures that the responses from the views will only be available if the user making the request is logged in and authenticated. Assuming we do not need our users to be authenticated to access the APIs, we wouldn't include the permission class. You can learn more about Permissions in Django REST Framework.

The full code in the views.py file is as follows:

from .models import Student
from rest_framework.generics import ListCreateAPIView,  RetrieveUpdateDestroyAPIView
from rest_framework.permissions import IsAuthenticated
from .serializers import StudentSerializer


class StudentList(ListCreateAPIView):
    permission_classes = [IsAuthenticated]
    queryset = Student.objects.all()
    serializer_class = StudentSerializer


class StudentDetail(RetrieveUpdateDestroyAPIView):
    permission_classes = [IsAuthenticated]
    queryset = Student.objects.all()
    serializer_class = StudentSerializer

Let us add our endpoints now.

Add API Endpoints

Now, we will create the API endpoints for the student application. We shall have two endpoints: api/students to create and get the list of students and api/students/<pk:id> to get, update and delete single students by their pk.

Create a urls.py file inside the students application directory and add the following imports inside:

from django.urls import path
from .views import StudentList, StudentDetail

Then, add the URL patterns for our endpoints in the urlpatterns list:

...
urlpatterns = [
    path('', StudentList.as_view()),
    path('<int:pk>', StudentDetail.as_view()),
]

int:pk above allows us to view the details of each student by going to an endpoint appended by the pk of the particular student.

The full code of the urls.py file of the student application is as follows:

from django.urls import path
from .views import StudentList, StudentDetail

urlpatterns = [  
    path('', StudentList.as_view()),                
    path('<int:pk>', StudentDetail.as_view()),
]

Next, let us connect the urls.py file of the student application to the urls.py file of the Django project.

Firstly, navigate to ~/drfauthproject/drfauthproject and open the urls.py file of the project:

cd ~/drfauthproject/drfauthproject
nano urls.py

Leave the code that is there already, but add the import to the students views and include as follows:

from django.contrib import admin
from django.urls import path, include # added the include keyword
from students import views # new line

...

Now, add the URL to the students app to the urlpatterns list:

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/students/', include('students.urls')), # new line
]

The full code of the urls.py of the project is:

from django.contrib import admin
from django.urls import path, include
from students import views

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/students/', include('students.urls')),
]

Now, we have the students application up. Next, let us move into creating authentication endpoints where users can make authentication requests.

Step 4 — Creating Authentication Endpoints

In this section, we shall create URLS patterns for our authentication endpoints. The authentication endpoints in our project will be mapped to the authentication views of the dj-rest-auth package. The views contain code that handles the various authentication functions such as registering users and logging in. You can see more endpoints and views provided by the dj-rest-auth package here, Dj-rest-auth API endpoints.

The views we shall be using are the following:

LoginView: the view that accepts sign-in requests
RegisterView: the view that will allow users to sign-up
VerifyEmailView: works with the endpoints for email verification during sign up
PasswordResetView and PasswordResetConfirmView: used for resetting passwords

Firstly, we will create a Django application called users to manage user accounts. This is where our register and login endpoints for users will be housed.

Navigate to the root directory of the project so you can use the manage.py script with the startapp command.

cd ~/drfauthproject/
python manage.py startapp users

Since we are going to put our register and login endpoints in the users app, we need to create a urls.py file inside there to add URL patterns for authentication. Navigate to the users app and create a urls.py file with the following commands:

cd ~/drfauthproject/users/
nano urls.py

Let us then add the new users application to the INSTALLED_APPS setting in the settings.py file.

...
INSTALLED_APPS = [
    ...
    'rest_framework',
    'rest_framework.authtoken',
    'students',
    'users'
]
...

Next, add a URL pattern to link the urls.py file of the project to the urls.py file of the users app.

Change directory to the project’s directory to access the urls.py file of the project:

cd ~/drfauthproject/drfauthproject/

The full code of the urls.py of the project is:

from django.contrib import admin
from django.urls import path, include
from students import views

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/students/', include('students.urls')),
    path(('users/'), include('users.urls')),
]

Now, we will add the authentication endpoints inside the Users app.

Dj-rest-auth Settings and Configuration

Next, let us install dj-rest-auth to handle authentication. We shall also install the django-allauth package to enable us to use the standard registration process of dj-rest-auth which is powered by django-allauth.

Install the packages with the following command on the command-line

pip install dj-rest-auth django-allauth

Next, add django.contrib.sites, allauth, and dj-rest-auth, to the list of INSTALLED_APPS in our settings.py file. We will also specifically add the registration module of the dj-rest-auth package, that is dj_rest_auth.registration to the list of INSTALLED_APPS to be able to use it in our project.

So, navigate to the root project folder and open the settings.py file.

cd ~/drfauthproject/drfauthproject/
nano settings.py

Then, add django.contrib.sites, allauth, dj-rest-auth and dj_rest_auth.registraion

...
INSTALLED_APPS = [
    ...
    'django.contrib.sites',
    'allauth',
    'allauth.account',
    'dj_rest_auth',
    'dj_rest_auth.registration',
    ...

Next, perform migrations for the newly added django.contrib.sites :

python manage.py makemigrations
python manage.py migrate

Next, we need to indicate the kind of authentication that we want for our REST API. We want token authentication so that API requests will be made with unique tokens. The Basic authentication type is also available where just the username and password are used to authenticate users. The session authentication type works by authenticating users by session contexts. You can learn more about the different types of authentication from the Django REST Framework documentation on Authentication.

Dj-rest-auth uses the JSON Web Token (JWT) for tokenization. Therefore, we shall install and use the djangorestframework-simplejwt library.

Let us use the pip package manage to install djangorestframework-simplejwt on the command-line:

pip install djangorestframework-simplejwt

Then, navigate to the settings.py file and add it dj_rest_auth.jwt_auth.JWTCookieAuthentication' to the list of the default authentication classes:

cd ~/drfauthproject/drfauthproject/
nano settings.py

Then add the following to the settings.py file

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'dj_rest_auth.jwt_auth.JWTCookieAuthentication',
    ],
}

Now, add SITE_ID = 1 in the settings.py file:

SITE_ID = 1

Next, set REST_USE_JWT to be True so that JWT authentication will be used by dj-rest-auth:

REST_USE_JWT = True

For every authenticated session, dj-rest-auth would return a Set-Cookie header that looks like the following:

Set-Cookie: my-app-auth=xxxxxxxxxxxxx; expires=Sun, 17 Feb 2021 14:21:00 GMT; HttpOnly; Max-Age=300; Path=/

Hence, you need to define what the cookie key will be called in your settings.py file. We can call it my-app-auth. So, put the following code inside the settings.py file of the project:

JWT_AUTH_COOKIE = 'my-app-auth'

Next, let us add the AUTHENTICATION_BACKENDS that will allow our users to be authenticated upon login and also to allow us to log in to the Django admin irrespective of the django-allauth authentication backend.

...
AUTHENTICATION_BACKENDS = [
    'allauth.account.auth_backends.AuthenticationBackend',
    'django.contrib.auth.backends.ModelBackend',
]
...

Next, let us specify that we want email verification for our project:

...
ACCOUNT_AUTHENTICATION_METHOD = 'email'
ACCOUNT_EMAIL_REQUIRED = True
ACCOUNT_EMAIL_VERIFICATION = 'mandatory'

We have just specified above that the email should be used for authentication instead of the username. We also specified that the e-mail address must be provided by the user in order to register. Lastly, we added the setting to ensure mandatory verification by email for the user to complete the registration process.

Next, we shall add the following code to the settings.py file:

ACCOUNT_CONFIRM_EMAIL_ON_GET = True
LOGIN_URL = 'http://localhost:8000/users/login'

The ACCOUNT_CONFIRM_EMAIL_ON_GET is to allow the website to verify the user when the user opens the link received in the email. Then, we want the user to be redirected to the LOGIN_URL after verification, so we specified our LOGIN_URL

Sign up and Sign in Endpoints

We will add the registration, login, and log-out endpoints first. Navigate to the users app folder and open the urls.py file inside the folder.

cd ~/drfauthproject/users/
nano urls.py

Add the following imports inside:

from django.urls import path, re-path
from dj_rest_auth.registration.views import RegisterView, VerifyEmailView
from dj_rest_auth.views import LoginView, LogoutView

As shown in the code above, RegisterView and LoginView are in the registration module of dj-rest-auth. Add the endpoints to the views in the urlpatterns list as below:

from django.urls import path, re_path
from dj_rest_auth.registration.views import RegisterView, VerifyEmailView
from dj_rest_auth.views import LoginView, LogoutView

urlpatterns = [
    path('register/', RegisterView.as_view()),
    path('login/', LoginView.as_view()),
    path('logout/', LogoutView.as_view()),

    path('verify-email/',
         VerifyEmailView.as_view(), name='rest_verify_email'),
    path('account-confirm-email/',
         VerifyEmailView.as_view(), name='account_email_verification_sent'),
    re_path(r'^account-confirm-email/(?P<key>[-:\w]+)/$',
         VerifyEmailView.as_view(), name='account_confirm_email'),
]

In the code above, we have added endpoints for registering users, logging in, and logging out. We have also added 3 endpoints to handle the email verification process of the user registration.

After a successful signup request, dj-rest-auth reaches out to the verify-email/ endpoint which processes the email verification and ensures that an email is sent via the account-confirm-email/ endpoint to the email address supplied by the user. A URL is sent along with the email message. The URL sent consists of the re_path to account-confirm-email/ and a unique key. The user can then verify the email address with the URL. re_path allows us to use regular expressions in our URL.

However, we want the verification process to be automatic once the user opens the URL received in the email. So, we will specify an endpoint to receive the unique key of account-confirm-email then verify the user.

Navigate to the users application and open the urls.py file.

cd ~/drfauthproject/users/
nano urls.py

Then, add the following path to the beginning of the urlpatterns list before the register endpoint:

urlpatterns = [
    path('account-confirm-email/<str:key>/', ConfirmEmailView.as_view()),
    ...
    ]

After verification, the user will be directed to the LOGIN_URL which we had earlier specified in the settings.py file.

You might want to check in Django admin to see if your domain is localhost or the default example.com. Navigate to the root directory of the project to use the manage.py script. Then create a superuser on the command-line with the following commands and follow the prompt to supply a username, e-mail address, and password for a superuser account:

cd ~/drfauthproject
python manage.py createsuperuser

Go to http://127.0.0.1:8000/admin and login with the credentials of the new superuser that you just created. Navigate to the Sites menu:

Select the site there to edit it. You may change the domain name to 127.0.0.1:8000 and the display name to localhost if they are not:

Changing the domain above to localhost will ensure that the e-mails that users will receive from us bear the localhost name and not the default example.com or any other. When you deploy to production, ensure that the display name is the name of the site and not the default example.com.

Adding Password Reset Feature

Now, we will allow our users to perform password reset when they forget their passwords. We will be adding the password-reset, and the password-reset-confirm' endpoints in the global urls.py file of the project for them to be active.

Navigate to the project’s directory and open the urls.py file of the project:

cd ~/drfauthproject/drfauthproject/
nano urls.py

Import PaswordResetView and PasswordResetConfirmView from dj-rest-auth views to the file

...
from dj_rest_auth.views import PasswordResetView, PasswordResetConfirmView

Next, add the following endpoints to the list of urlpatterns as shown below:

urlpatterns = [
    ...
    path('password-reset/', PasswordResetView.as_view()),
        path(‘password-reset-confirm/<uidb64>/<token>/',
         PasswordResetConfirmView.as_view(), name='password_reset_confirm'),  
]

The password-reset endpoint is where the user makes the request to reset their password. dj-rest-auth calls unto password-reset-confirm endpoint to which sends an email to the email address of the user. The email message body contains the password-reset-confirm that has a unique key to verify only that email address. When the user opens the password-reset-confirm URL in the email message, they will be redirected to a new page to supply a new password for their account.

The full code of the main urls.py file of the project now becomes:

from django.contrib import admin
from django.urls import path, include, re_path
from students import views
from dj_rest_auth.views import PasswordResetView, PasswordResetConfirmView

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/students/', include('students.urls')),
    path(('users/'), include('users.urls')),

    path('password-reset/', PasswordResetView.as_view()),
    path(‘password-reset-confirm/<uidb64>/<token>/',
         PasswordResetConfirmView.as_view(), name='password_reset_confirm'),
]

Email Backend Configuration

We need to set up the configuration for our email backend server so we can send verification emails to the users.

Navigate to the settings.py file and open it:

cd ~/drfauthproject/drfauthproject/
nano settings.py

Add the following code to the settings.py file:

...
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_USE_TLS = True
EMAIL_HOST = 'smtp.gmail.com'
EMAIL_HOST_USER = 'email@gmail.com'
EMAIL_HOST_PASSWORD = ********
EMAIL_PORT = 587

In the above code, we specified the Django service to be used for doing email in our app. We also defined the EMAIL_HOST as the Gmail email server. We added our email address and password as EMAIL_HOST_USER and EMAIL_HOST_PASSWORD respectively. Replace the value of the EMAIL_HOST_USER and EMAIL_HOST_PASSWORD with your Gmail email address and password.

Please note that we have put the values for the configuration settings in our settings.py file because we are still in the development stage and we test on our localhost. During production, make sure you put the above configuration inside your .env environment variables so that they would be secret and would not be available to the public.

Next, sign in to your Gmail account and allow less secure apps in your Gmail account here, Less secure apps access. This will prevent Google from blocking access to your Gmail account when you want to use it to send confirmation emails to users.

Now that we have set up our authentication endpoints and email backend server configuration, we will test the endpoints.

Now, navigate to 127.0.0.1:8000 and you will see the endpoints listed out as shown in the picture below:

Step 5 — Testing Authentication with the Browsable API

Django REST Framework ships with the Browsable API which has a good and simple interface for interacting with APIs. We shall make use of the browsable API to test our newly created REST API. If you navigate to any of the endpoints that we created, you will see the browsable API. For example, navigate to http://127.0.0.1:8000/api/students/ to see how the browsable API looks like. it should look like the following:

However, we cannot access the HTTP actions and resources provided by the student list endpoint because we haven’t been authenticated. We need to provide login details in order to be able to use the students app endpoints. But before login, we need to register a student. Now, let us register to create a new student instance. We shall do this through the register endpoint. Navigate to http://127.0.0.1:8000/users/register/ to see the page looking like the following:

Then, you should get a response, Verification e-mail sent. with the HTTP response code 201 Created as thus:

The user would receive an e-mail like the following:

When the user opens the URL they received via email, they will be redirected to the login endpoint which looks like the following on the browsable API:

Now, login with the login credentials that you registered with. Upon successful authentication, you should get a 200 OK response, two tokens, and the user details and as shown below:

Along with the details of the user returned upon login, we have 2 tokens returned. These are the access and refresh tokens:

Access token: this is the token that allows you to have access to the API. It has a short life span before it expires.
Refresh token: consists of the information that will enable you to get a new access token when the previous one has expired.

If you navigate to the student list endpoint now at http://127.0.0.1:8000/api/students/, you should be able to access the endpoint since you have been authenticated. The browsable API endpoint should look like the following:

Input the first name, last name, email, and classroom of a sample student, you should get a HTTP 201 Created response and the new student added shown in the list. It will like the following:

Here, because we used the ListCreateAPIView generic view, we get a list of students on this endpoint, we also have options to create a new student.

Now, let us check the details of the particular student added, go to the endpoint http://127.0.0.1:8000/api/students/1. 1 is the primary key of the student that goes into the StudentDetail path in the urlpatterns list of the students app. It should look like this:

Because we used the RetrieveUpdateDestroyAPIView generic view, we can view the details of a particular student (retrieve), we can edit the details of that student (update) and we can delete that student (destroy).

Next, let us test the Password reset endpoint Navigate to 127.0.0.1:8000/password-reset/ on your browser. It should look like the following:

Input the e-mail address. You should get a detail message as shown below:

The user will receive an email with a URL in their inbox. The e-mail message will look like the following:

When the user opens the URL in the email body, they would be required to supply a new password with the uid and token values in the URL as shown in the browsable endpoint below:

When the user opens the URL they received in the e-mail, they will be redirected to password-reset-confirm page to supply a new password and the uid and token values. To handle this part, you will need to configure your client-side app to get the uid and token parameters from the link in the email body when the user opens it. You can check how to do this with React, a JavaScript framework for frontend apps in this Stackoverflow discussion

You can get the full code of this project on Github.

Conclusion

We have been able to learn how to setup authentication for Django REST APIs. We also implemented smptp with Gmail for the verification of e-mail addresses used to register. We implemented endpoints for users to register, login, logout, verify emails, and reset passwords in cases where they forget their passwords.

Hopefully, you should be able to implement authentication and authorization in your Django projects with RESTful APIs. You may go and integrate client-side apps with React.js, Vue.js, Angular.js, and other frontend frameworks and libraries. You would however need to implement the cross-origin resource sharing (CORS) headers in your Django backend to effectively serve responses to requests from the client-side apps. You may use the django-cors-headers tool for this. Follow the good straightforward documentation of the django-cors-headers on how to install and use the module.

Thanks for patiently reading through this article. Please do not hesitate to share your opinions and ask questions. You may connect with me on Twitter @jkaylight.

2020 2020: My Review

JekayinOluwa Olabemiwo — Thu, 14 Jan 2021 13:07:13 +0000

I survived!