JavaScript Weather App - Part 1 ~ API Design

Introduction

Hello all! 

This will be the first of the article collection that we will be going through to implement a simple weather app using JavaScript for the full stack. The weather app would have:

1. A Rest API that would give us current and forecasted weather for predefined locations

2. A web application that would display the current and forecasted weather of a selected location

To achieve the above, we would need to make some decisions. 

Since we are going to pursue everything using JS, we could easily use NodeJS to implement a backend server that would deploy the Rest API. For the front end app, we do have a lot of choices, but in this tutorial, we will be using React. We also need some sort of DB integration to read the weather data from. To limit the scope of this tutorial, let's skip how the data is entered and worry only about reading data from the database. 

In this tutorial, we will be talking about the following topics:

1. Part 1 - The architecture and API design

2. Part 2 - Backend implementation

3. Part 3 - Front end implementation ~ Basics

4. Part 4 - Front end implementation ~ Components

In Part 1, we will be discussing about the architecture and the design considerations of the API. We will be talking about:

1. A proposed architecture for the backend and client apps
2. A little introduction to Rest APIs
3. Proposed API endpoints and their parameters and responses

The Architecture

As mentioned above, the purpose of this tutorial is to implement a simple weather app using JavaScript. It might sound like one big app, but it could be easily reusable and made more independent if we have 2 different apps for the backend and frontend respectively. Implementing a Rest API would basically mean the same thing.

In terms of the data, we could integrate a database and expose the data in the Rest API, which can be called by any third party app and display the data any way they like. Think of our backend as something similar to the Yahoo or the OpenWeatherMap API.

So the architecture I would go for would be as follows:

As you can see, the 3 main components would be our backend, frontend and the DB. 

Starting the implementation of the client app first would not be a very good idea, because you would not have an idea about the data you would be getting from the APIs. So the best course of actions (or the TODO list) would be as follows:

1. Design the APIs

2. Implement the APIs (backend)

3. Implement the client App

So let's get ready to tick-off our first to-do item!

API Design

If you're an expert on Rest APIs, you may skip the following section, but everyone else, gather up for a very brief introduction to Rest APIs and the bits of information you should absolutely know about Rest APIs.

A RESTful API is simply an application program interface (API) that uses HTTP requests to exchange data (communicate) between components. These communications can be of the following types:

• GET - read data
• PUT - update data
• POST - insert data
• DELETE - delete data

Restful APIs should always comply to the following constraints:

1. Use of a uniform interface (UI) - The purpose of Rest APIs is to communicate with servers to get/update information on resources. And this constraint simply means that any resource should be defined using URIs (uniform resource identifiers) that should be self descriptive. For example, if an API is used to retrieve details of a book "/books/1234" is resource based and is a better design than "books/the+book+I+bought+today" as the latter doesn't seem like a uniform identifier for a book.
2. Client-server based - There should be a clear delineation between the client and server. UI and request-gathering concerns are the client’s domain. Data access, workload management and security are the server’s domain. This loose coupling of the client and server enables each to be developed and enhanced independent of the other.
3. Stateless operations - All client-server operations should be stateless, and any state management that is required should take place on the client, not the server.
4. RESTful resource caching - All resources should allow caching unless explicitly indicated that caching is not possible.
5. Layered system - REST allows for an architecture composed of multiple layers of servers. So it is valid if a client app doesn't know if he is directly calling a server or if it goes through multiple layers that would finally land on the server.
6. Code on demand - Most of the time a server will send back static representations of resources in the form of XML or JSON. However, when necessary, servers can send executable code to the client.

Now let's think about how the weather APIs could be used and what kind of data to be exposed.

If the end user has the ability to select a location, he should be provided with a list of locations to choose from. Therefore we need one API to list the locations.

Secondly, when the end user picks a location, the current and the forecasted weather should be delivered, therefore the second API we need is the weather API which is bound to a selected location.

Additionally, I thought of letting the developers know the list of supported weather conditions, so that they can easily configure the icons and what not to show on their client applications. Therefore an additional weather condition API too would be implemented.

Considering all of the above, the following are the APIs that I came up with:

1. GET   /locations - Retrieve list of locations that can be forecasted ordered alphabetically by the city
2. GET   /conditions - Retrieve list of supported weather conditions
3. GET /forecasts - Retrieve weather forecast of a city defined by query parameter, responding with an array of 10 forecast items. (Optional "limit" query parameter can define the expected forecast count)

You can use editor.swagger.io to interactively view the full API definition (with the input/output definitions) in yaml is hosted in Github, which is added in the end of this article to avoid clutter.

In order to make things easier, I designed the database to match the API design, which has exactly 3 tables following the ERD (make sure to populate dummy data to view in the app):

That will be all for now, and let's talk about implementing the backend in the next chapter!

The complete API definitions:

You can use editor.swagger.io to interactively view the full API definition (with the input/output definitions) in yaml is hosted in Github.