Building a React Based Single Page Application to Consume an API Deployed in WSO2 API Manager

Photo credits: Glenn Carstens-Peters on Unsplash

In this post, you’ll learn to build a very simple web application with React. After that, you’ll deploy the sample Pizzashack API in WSO2 API Manager and invoke it from the React app using OAuth2 Implicit Grant Type. So, roll your sleeves up and get ready to dive deeper into the code level!

TL;DR (For the Impatient)

I must say that this post is going to be pretty long and full of code snippets. You can try out the code snippets while reading. But for those who need to skip the post and get into the source code, here’s the GitHub repo URL.

Before You Begin

I assume you have a basic knowledge of Javascript, REST APIs, React, and OAuth2 fundamentals. If not, I recommend you to refer to below resources and come back.

• React
• OAuth2
• WSO2 API Manager

What Are We Going to Build?

We’ll end up building a simple React app to fetch and render a pizza menu from a REST API that is deployed inside WSO2 API Manager. The screenshot below shows how it would look when we are done.

The final shape of our application

Use case scenario

Let’s assume customers have already registered with PizzaShack and they are using these account credentials to access the pizza menu. The main use case scenario and flow of user interactions would be like below:

• When a typical user visits the client application we are going to build (https://localhost:3000), they’ll be presented with a link to login.
• Login link redirects the user to API Gateway, asking them to provide the user name and password.
• API Gateway authenticates the user on behalf of the client application.
• Upon successful authentication, API Gateway redirects the user back to the client application.
• Then the user may access the menu page by clicking on the menu link (in the navigational bar) of the client application.

Above is a very high-level flow and it only focuses on the user interactions. But we’ll be digging into the detail of each step very soon and I’ll show you how to realize each step technically. So let’s get to work…

API Gateway Configurations

For this post, We are going to use WSO2 API Manager as our API management platform. It is an open source approach that addresses full API lifecycle management, monetization, and policy enforcement. What really attracted me to this product is the flexibility it offers for customizations and experimentation while maintaining the ease of use and manageability. Above all, it’s available free of charge. So head out to the downloads page and download any distribution/form-factor you are comfortable with.

Once you download distribution of your choice, I’d recommend you to go through the quick start guide to get it up and running. From here onwards, let’s refer to WSO2 API Manager as APIM for short.

Deploy PizzaShack API sample

APIM comes with a sample API implementation called PizzaShack. It mimics a fictitious pizza shop and provides several resources to browse the pizza menu and manage orders over REST. You don’t have to worry about deploying a backend since the sample comes with its own embedded backend service. PizzaShack sample is not deployed in the Publisher by default. So let’s go ahead and deploy it.

Start the APIM and login to the Publisher component using this URL pattern.

https://:/publisher

E.g If you are running APIM in your local laptop, the URL would be https://localhost:9443/publisher

The Publisher is the place where you author APIs. Here, as a developer, you can design APIs, impose policies on them, change their lifecycle state, create a new version, and view usage metrics/statistics. Once you are done, you will publish the APIs so that they’ll appear in the API Store and API Gateway for the consumption. When the login screen is prompted, log in with the default admin credentials; use “admin” for both username and the password.

Publisher component of APIM

Instead of creating an API from the scratch, let’s simply deploy a sample API that is being shipped with the APIM distribution. When you log in to Publisher for the first time, you’ll see a button called Deploy Sample API in the API list. Click on it and follow the on-screen instructions as follows:

Click on the highlighted button to deploy the sample

Create an OAuth application and obtain application keys

Once deployed, you’ll see PizzaShack API in the Developer Portal. It is the place where all the published APIs are listed so that API consumers (developers mostly) can search, try out and subscribe. Use the URL pattern below to access the Developer Portal:

https://:/store

E.g If you are running APIM in your local laptop, the URL would be https://localhost:9443/store

PizzaShack sample deployed to Developer Portal

Now let’s create an Application to subscribe for this sample API.

• Sign In into the developer portal with default admin credentials (admin for both username and password).
• Click the Applications menu and click Add Application to create a new application.
• Enter the name as ReactApp and leave other settings as it is.

In the next screen, select the Production Keys tab and enter https://localhost:3000/callback as the callback URL. Once you complete the entry, Implicit and Code grant type checkboxes will be activated. Go ahead and check both of them. Finally, click on Generate keys button to generate application keys for your application.

In the next screen, you’ll be presented with the application keys. At a later stage, you’ll be needing the consumer key to generate the token from the client app. Let’s explore that later.

OAuth client Id and client secret

Finally, go to APIs and select PizzaShackAPI. Subscribe to it with the ReactApp application you just created.

Select ReactApp as the application upon subscription

Now you have deployed the sample API and created an OAuth application for your React app. Those are the only configurations required from the APIM side. So now its time look at the client app.

Implementing the Client Application

Single Page Applications and React

A Single Page Application (SPA) is a web application that loads a single HTML page initially and dynamically update that page as the user interacts with the application. A SPA works inside a browser and does not require page reloading during use. The apps you use on a daily basis including Gmail, Facebook, Google Docs, and Google Maps are SPAs. React is a Javascript UI library created by Facebook. Developers use React to build component-based modular SPAs and it’s very popular among frontend developers.

Scope of our client application

Our client application is a simple React based SPA. It’ll invoke the /menu resource of sample PizzaShack API deployed in the APIM and renders the menu items received in the response. But we have a problem here. The PizzaShack API has been protected with OAuth2 by default. So any consumer/client application that wishes to access that API must obtain an OAuth2 access token from APIM prior to invoking the API. So we’ll be adding OAuth2 based API authentication and authorization logic to the React app as well.

Creating the React app

With our sample PizzaShack API up and running, now the time has come to start developing the React app. Creating a React app used to be a bit messy process in the past. But fortunately, Facebook came up with a nifty tool called create-react-app to scaffold a React application from scratch, which will dramatically decrease the workload of the developer.

To get things started, open a terminal and move to a directory where you usually create projects. Then issue the command below:

What happens here is NPM downloads and runs the create-react-app snippet in one go. It’ll take the provided argument react-pizzashack-client as the application name and creates a new directory inside the current working directory. This process might take a few seconds depending on your environment and the network connectivity.

Once the above command returns, move into the generated directory and issue below command to run the React app.

npm start command will open a development server on port 3000 and listens for incoming connections. Also, it’ll open the application in a new browser tab. Or else, just navigate to https://localhost:3000 to see you freshly brewed app in action.

The default screen you’ll see with create-react-app

The development server will take care of automatically deploying the changes you do to the code and they will be immediately reflected. Press Ctrl + C to shut down the development server. Once the server is stopped, you can configure your favorite IDE to edit the React application. Mine has always been the VS Code. In the same terminal, you can optionally issue below command to start a new VS Code project with the generated React app.

Get rid of unwanted default files

The React app you just generated contains a few files that you won’t be needed in the future. So remove below files from your React project.

• ./src/logo.svg
• ./src/App.css
• ./src/App.test.js

Then open up ./src/App.js and remove below lines. Otherwise, the project will not get compiled.

Finally, locate the below line in the same file and remove that as well.

The whole point of removing unnecessary files at early stages is to keep the app simple and refactored so that you know what you are doing. That will help you to avoid unnecessary compilation failures and focus on the actual problem instead.

Add Bootstrap into React app

Now we have a basic React app with its default look and feel. But I need to walk up the extra mile and spice up the UI with some fine looking styles and widgets. So I’m gonna add the Bootstrap library to the project. There are many ways to do this. You could use the react-bootstrap library if you intend to develop a fully pledged UI with user interaction, and animations, etc. But for the sake of simplicity, I’ll just add the Bootstrap CSS file hosted in their CDN. It is just a matter of adding the link to the CSS file in index.html. To do that, open up the public/index.html file and copy-paste the below stylesheet into the section.

Create React components: Home and NavBar

Let’s quickly create two React components; Home and NavBar. Purpose of the Home component is to act as the landing page and display a message to the user. NavBar component acts as the navigational bar for the application. Create a directory called components inside /src directory to put all our components. Then create /src/components/Home.js file and insert below code into that:

View raw

The Home component is a simple stateless functional component that simply displays a Bootstrap Jumbotron with a greeting message. Next, create src/components/NavBar.js and insert the below code into that:

View raw

The NavBar component is a simple Bootstrap navigational bar which displays the name of the app, menu link, and Sign In/Sign Out links. We’ll be rendering the Menu link and Sign In/Out buttons conditionally, depending on the user’s status in a later section. But for now, let’s leave the navbar like this. Finally, open /src/index.css file and add below entry inside body {} declaration.

Now we have two components in place. Let’s configure routes to them and ask React to render them.

Configure React Routes

Before getting our hands dirty with React Routes, let me breakdown the behavior of this React app for an ordinary user. There will be two scenarios when a user navigates to the root context of the app. That means, simply https://localhost:3000

• For anonymous users

They should only see the home component.

• For authenticated users

Users who have been successfully authenticated should be able to see the home component and the menu component, which will render a grid of Pizza menu items. (We’ll be creating this component at a later section in this post. So hang tight!)

That’s it! Pretty simple, right? The reason I chose to display the pizza menu only for logged in users because of the API resource that provides the menu data is protected with end user’s credentials. So our React app should obtain an access token on behalf of the logged in user. Hence the menu page is protected.

Let’s discuss that in detail very soon. Until then, allow me to install router dependencies and set up a route to render the anonymous view. Stop the development server by pressing Ctrl + C, if it is running already. Get back to the same terminal and type the command below:

The above command will install two libraries; react-router which provides the navigational capabilities to the application while react-router-dom provides the required DOM bindings for the React Router implementation. Now we have the required dependencies installed. So let’s start the routing configurations.

First, open the ./src/App.js file and replace its content with this.

View raw

In the above code, you just imported BrowserRouter from the react-router-dom library and wrapped all components with it. In order to enable routing within your application, this is all you have to do. You can refer this guide to get more familiar with React Routers and their various behaviors.

Finally, let’s add a route to the exact path “/”. So whenever a user lands on the applications root context (https://:/), this is the route that’s going to get triggered and it simply renders the Home component. Regardless of any route, NavBar will always be rendered at the top of the page. When you run the app with npm start, you’ll see the below screen which marks our progress up to this point.

Securing your React app

Up to now, your app is functional with a sleek navigational bar, a home page, and a menu page that displays just two menu items. React routes are working as expected and they’ll land your users into correct spots. Now the time has come to take things to the next level and add some security features to your React app to perform the following:

• Implement the Sign In functionality for your end users.
• Implement the Sign Out functionality.
• Invoke the real PizzaShack API with an access token and render the results in the menu page.

But before we start the implementations, let’s have a closer look at how PizzaShack API has been protected inside WSO2 API Manager.

A brief primer on Implicit Grant type

Usually, Single Page Applications use OAuth2 Implicit Grant type to get an access token without an intermediate code exchange step. It’s pretty much similar to the Authorization code grant type but there’s no server-side component involved. The Implicit Grant starts out by building a link and directing the user’s browser to that URL. At a high level, the flow has the following steps:

• The application opens a browser to send the user to the OAuth server.
• The user sees the authorization prompt and approves the app’s request.
• The user is redirected back to the application with an access token in the URL fragment.

Implicit grant flow can be visualized like below:

Implicit grant flow

In the above diagram, Client will be your React app and the authorization server is WSO2 APIM.

How PizzaShack API is secured?

All APIs deployed in WSO2 APIM is protected with OAuth2 security protocol by default. For PizzaShack API, it follows the same rule and we need to obtain an access token under Implicit grant type before invoking it.

Our plan to obtain an access token

Our plan is pretty simple and has 3 steps:

• Add a click handler to Sign In button in NavBar component so that it’ll redirect the user to the /authorize endpoint of APIM and will be presented with a login form.
• Upon successful authentication, APIM redirects to the callback URL we have provided with the access token in the URL fragment.
• We need to extract the access token from the URL hash, validate it and save it to the localStorage to be used later.

Now let’s start this plan by creating the Config.js file inside /src directory. This file holds all necessary OAuth configurations related to your React app.

Note: Make sure to replace clientId with the consumer key, you received for your client application (ReactApp) in WSO2 APIM. Here, the authUrl parameter is the endpoint where WSO2 APIM provides the login page. callbackUrl is the URL we have provided when registering our client application with WSO2 APIM. Upon successful user authentication, APIM redirects the user to this URL.

Create Auth.js to keep all authentication related logic

Then let’s create a new class called Auth to put all authentication and authorization logic so that you can re-use it from other components. Create the Auth.js file inside /src/components directory and insert the following code:

View raw

Config.js we just created and builds up the redirect URL. In addition to that, we have two properties, accessToken and expiresAt which is keep track of the access token and the expiry time of the token. We’ll be using these properties in a later section of this post.

Enable users to sign in with NavBar

Now let’s update our NavBar component to attach a click handler to Sign In button so that users will be redirected to the login page upon a button click event. Replace the content of NavBar.js with below code:

View raw

In the above file, the Sign In NavBar component receives the Auth object passed from the Router, via props. In order to tell the router to pass that object for us, we’ll have to wrap our component with withRouter higher order component. Also, you’ll see a click handler called login() is attached to the Sign In button which in turn calls the login() method of the Auth object passed via the props. Now if you run the application, you’ll see the below screen when you click on the Sign In button. That is the default login form provided by WSO2 APIM.

For the moment, provide admin for both username and password. Once you have users registered in APIM, you can use their credentials. Then you’ll be presented with the default Open ID consent page that asks for your permission to grant access to your personal attributes to the React app. Select Approve Always and Select All as per the screenshot.

When logging in for the first time, APIM asks for the OpenID consent

After successful authentication, you’ll be redirected back to the React app. But you won’t notice anything special as of now. So let’s create a new component to extract the access token issued from APIM.

Handling the response received from WSO2 APIM

Okay, now we have APIM redirecting to the callback URL of your React app, with an access token attached to the URL hash. So let’s create a component to catch that URL hash, parse it and store in the localStorage.But before that, we need to install a third-party dependency to our project. Open up a terminal and navigate back to you React project’s root directory. Run below command to install query-string npm package which will be helpful with parsing the URL hash coming from the APIM.

Then add below method into Auth.js:

View raw

This handleAuthentication() method parses the URL hash fragment received from WSO2 APIM. It uses the query-string package for that and assigns the parsed response into a JSON object. If the response is valid and has an access token in it, we populate variables and set isLoggedIn flag in localStorage. Also, we save the received access token to localStorage as well. Moreover, let’s add a few more methods to Auth.js; logout() , getAccessToken(), and isAuthenticated() which we’ll be using very soon. Now your Auth.js should look like this.

Create the Callback component

Let’s create a new component to handle the redirection route from APIM. Create a file named Callback.js inside /src/components directory and insert the below code:

View raw

Inside componentDidMount() method, we are invoking the handleAuthentication() of Auth class passed via props. If the authentication succeeds, we redirect the user to the root context (https://localhost:3000) of our React app using the history object. Since we need to get access to Auth object via props and need to use history object for navigation, we wrap this with withRouter.

Then go to App.js and add this import:

Also, add this route as well:

You can see the way we are passing the initialized Auth object into the Callback component in this route definition.

Adding Auth checks and sign out functionality

Now our app can sign in users and extract the access tokens coming from APIM. Now let’s try to use that token and logged-in state to do some access control within the app. First, let’s change the NavBar code to render the Sign In button if the user is not logged in. Otherwise, let’s render a ‘Sign Out’ button. Replace the content of NavBar.js with this code.

This is the final version of our NavBar component and it has a new method; logout() and I have put some logic to check for the authentication status of the user. Here, I’m calling isAuthenticated() method of the Auth object passed in. Inside that method, the user’s authentication status is being checked.

Above code in Auth.js checks the received access token’s expiry time against the current time. Depending on the value returned by isAuthenticated(), NavBar shows Sign In or Sign Out buttons accordingly as follows:

Implementing the logout functionality

In the case of the Sign Out button, I’ve defined logout() which in turn calls logout() method of the Auth object and redirects the user back to the home page of the app. Now save the NavBar.js and refresh the app. After you log in, you’ll see the Sign Out button in the navbar, which will allow you to log out from the application. Up to now, we have lifted the heaviest parts of the app, which is about getting your users authenticated. I’ll assure the rest will be a smooth ride and you reap the benefits from the things you have implemented in this phase.

Invoking the PizzaShack API From Your React App

At last, we have reached the final part of this post. I assume it’s been a long drive from up there. But have no fear, we’ll be done very soon. Our plan is to create a new component called Menu to render a list of menu items. We should write code inside this component to call the PizzaShack API in APIM with the access token, fetch the response and render the list in a nice format. NavBar.js already has a link to access this component and it’ll only visible to logged in users. But we don’t have a Route for that yet. So let’s begin by creating a route for the Menu component.

Go to App.js and add the import below:

Then add this route as well:

Above route tells React to route all requests coming from /menu path to Menu component.

Install axios library

Inside the Menu component, we’ll have to make an HTTP GET call to APIM and fetch data. In order to do that, we need the axios library, which is a promise-based HTTP client for the browser. Stop the development server and issue the below command to install axios library.

Fetching and rendering data

Create /src/components/Menu.js file and put below code into this.

Make sure to update the value of API_URL to match with your APIM hostname. This Menu component is a stateful component and it holds a list of menu items as the state. Initially, the state will be an empty array. But once the component reaches the componentDidMount() lifecycle method, it’ll fetch data from APIM with the access token received with the help of axios client. Upon the arrival of response data, it’ll be set as the internal state by calling this.setState(). When render() is called, it simply iterates through the internal state (menu items array) and renders a pretty Bootstrap card columns structure. And finally, we have our Pizza menu rendered like below:

Closing Remarks

I humbly believe you have learned something from this post. I admit that it’s quite long. But I tried my best to touch upon even the smallest steps hoping that they’ll add some value to you. Please keep in mind that this is just a simple reference application I created only to demonstrate how React apps can collaborate with WSO2 API Manager. This might not be perfect for production deployment. But it’ll give you sufficient guidelines to start off.

You may use the source of this app as a boilerplate to start your own adventure. Also, you can send pull requests with improvements. I’d be more than happy to merge them. Cheers!