In this tutorial, we will create a single reusable module that can perform all of our API calls in less than 50 lines of code! (Jump to final module code here). If you're familiar with the fetch API, you've seen how it could start to look ugly and unreadable with all of the promise chains.
fetch(url)
.then((response) => response.json())
.then(data => {
console.dir(data);
});
})
Ew. You don't want to be doing that for every API call in your app. We should abstract this into a module so that your calls become more legible and easier to make. API calls will then look like this:
async function getArticles(userId) {
const articles = await Fetch.get('/articles/' + userId);
articles.forEach(item => {
// iterate through results here...
});
}
We will be using ES6 modules in this tutorial. Let's go! (Take note of async and await keywords).
Create a Fetch.js module skeleton
First, let's define our public CRUD methods that we will use to interact with our module and define the API host:
// Fetch.js
const _apiHost = 'https://api.service.com/v1';
export default {
get,
create,
update,
remove
};
Create the main fetch method
Next, let's make a private method inside our module that performs the actual fetching. This general purpose method should be able to handle both read and write API calls. Our method will take 3 arguments:
- url - the API endpoint - ex: '/articles'
- params - additional parameters to pass to the endpoint as either a query string for GET or data for the body of the request on POST, UPDATE, and DELETE calls
- method - GET (default), POST, PUT, DELETE
// Fetch.js
// ...
async function request(url, params, method = 'GET') {
}
// ...
Notice the async at the beginning of our function. We need this because we are going to deal with Promises.
Add options and make sure to use "await"
// Fetch.js
const _apiHost = 'https://api.service.com/v1';
async function request(url, params, method = 'GET') {
// options passed to the fetch request
const options = {
method
};
// fetch returns a promise, so we add keyword await to wait until the promise settles
const response = await fetch(_apiHost + url, options);
const result = await response.json(); // convert response into JSON
// returns a single Promise object
return result;
}
// ...
Handle parameters for all request types
We want this method to be able to handle any parameters that may need to be included as part of the API request. For GET requests, we need to support query string . For all other write-related requests, we need to be able to include a body to the request.
We want our module to be super easy to use so let's standardize on handling objects for all cases. We can then convert the object into a query string for GET requests and include the object as JSON as part of the request body for all other types.
Let's create our object to query string conversion method:
// Fetch.js
// ...
// converts an object into a query string
// ex: {authorId : 'abc123'} -> &authorId=abc123
function objectToQueryString(obj) {
return Object.keys(obj).map(key => key + '=' + obj[key]).join('&');
}
// ...
Now we can add some code to handle the parameters if they exist. Let's add this right after the options definition in our request method:
// Fetch.js
const _apiHost = 'https://api.service.com/v1';
async function request(url, params, method = 'GET') {
const options = {
method,
headers: {
'Content-Type': 'application/json' // we will be sending JSON
}
};
// if params exists and method is GET, add query string to url
// otherwise, just add params as a "body" property to the options object
if (params) {
if (method === 'GET') {
url += '?' + objectToQueryString(params);
} else {
options.body = JSON.stringify(params); // body should match Content-Type in headers option
}
}
const response = await fetch(_apiHost + url, options);
const result = await response.json();
return result;
}
function objectToQueryString(obj) {
return Object.keys(obj).map(key => key + '=' + obj[key]).join('&');
}
// ...
Create public methods
Excellent! Now let's create the four public methods that we can use to make our different requests. We will export a single object that references these four methods at the very bottom of our module.
// Fetch.js
// ...
function get(url, params) {
return request(url, params);
}
function create(url, params) {
return request(url, params, 'POST');
}
function update(url, params) {
return request(url, params, 'PUT');
}
function remove(url, params) {
return request(url, params, 'DELETE');
}
Error Handling
It's a good idea to add some error handling to our module. One way is to check the status code of the response. If it is NOT 200, then we should return some kind of error message.
You may handle errors any way you want. In this example, we will return an object with a status and message. Let's check the status immediately after our fetch request:
// Fetch.js
// ...
const response = await fetch(_apiHost + url, options);
// show an error if the status code is not 200
if (response.status !== 200) {
return generateErrorResponse('The server responded with an unexpected status.');
}
const result = await response.json();
return result;
}
// A generic error handler that just returns an object with status=error and message
function generateErrorResponse(message) {
return {
status : 'error',
message
};
}
We did it!
Now we can make all four types of API requests using a single module!
async / await
Our Fetch calls return a single promise so we need to use the await keyword in front of our calls. Additionally, await keyword does not work on top level code so they must be wrapped inside an async function. Here's what these requests may look like:
import Fetch from './Fetch.js';
// GET
async function getAllBooks() {
const books = await Fetch.get('/books');
}
// POST
async function createBook() {
const request = await Fetch.create('/books', {
title: 'Code and Other Laws of Cyberspace',
author: 'Lawrence Lessig'
});
}
// PUT
async function updateBook(bookId) {
const request = await Fetch.update('/books/' + bookId, {
title: 'How to Live on Mars',
author: 'Elon Musk'
});
}
// DELETE
async function removeBook(bookId) {
const request = await Fetch.remove('/books/' + bookId);
}
Our completed API interface module! - Next Steps
I hope that you enjoyed this tutorial and that you can use it to become more productive!
You can add all sorts of other options to this module and in the fetch request itself. For example, what parameters would you add to the fetch method to support CORS requests?
How would you handle file uploads?
Happy Fetching!
// Fetch.js
const _apiHost = 'https://api.service.com/v1';
async function request(url, params, method = 'GET') {
const options = {
method,
headers: {
'Content-Type': 'application/json'
}
};
if (params) {
if (method === 'GET') {
url += '?' + objectToQueryString(params);
} else {
options.body = JSON.stringify(params);
}
}
const response = await fetch(_apiHost + url, options);
if (response.status !== 200) {
return generateErrorResponse('The server responded with an unexpected status.');
}
const result = await response.json();
return result;
}
function objectToQueryString(obj) {
return Object.keys(obj).map(key => key + '=' + obj[key]).join('&');
}
function generateErrorResponse(message) {
return {
status : 'error',
message
};
}
function get(url, params) {
return request(url, params);
}
function create(url, params) {
return request(url, params, 'POST');
}
function update(url, params) {
return request(url, params, 'PUT');
}
function remove(url, params) {
return request(url, params, 'DELETE');
}
export default {
get,
create,
update,
remove
};
Top comments (23)
You need to make sure you're encoding your query parameters as URI components :) nice article!
Next steps I would take to expand this would be thinking about how you can allow headers to be configured on a per request basis, adding things like interceptors and support for form-data requests, canceling requests, and so on.
Wouldn't you need to
await
though?Yes you're right! Sorry I forgot this very important aspect. And the call needs to be wrapped inside an async function. I've corrected the code examples. Thank you!
In the final version, I see export default {
get,
create,
update,
remove
}; In the examples I see import of Fetch and you're using Fetch.get. Is it better to export default or export as a named class?
That's entirely up to you. Personally, I like to use export default in this instance to provide context. Fetch.get() adds some clarity to my code, but that's just my opinion:
Thanks for the clarification. How should the export look? The export above is written as: export default {
get,
create,
update,
remove
};
When I imported Fetch, it wasn't working? Btw, great article!
It should look like this:
Depending on the location of your Fetch.js file, the path could be different.
Hello!
Suppose I create a BookController and have a function below in this controller:
Could I export this function to call it in another js file?
Another thing, is it possible to make the constant books a global variable and export that variable so that I can use it anywhere?
Yes, you can export it. Regarding global access, I like to create a new module for that. In my case, I called it Store.
I then include this in my modules whenever I need to access a global variable.
thanks for the return, it was of great help!
Just one more question and I will always be grateful!
Suppose I require the data from bookId = 1 and want to display the attribute data in a Modal component (we can imagine the bootstrap), I would also like to change any value of any field, imagine the title of the book and save next.
In the code below, I'm just giving you an idea! Can you help me organize this code?
Hi, can I resolve the promise this way?
Thinking about it, what is the best way to do this?
I want to call this function in another file, but I would like the promise to be resolved
You can import this file for use in another file. First you will need to export that function. You can do using a number of ways, but here's a way using named export:
Then in your other file:
I am having trouble using this for creates and updates. The create works fine when using a form object but if just sending a regular object there is a problem. On the client side:
try {
let response = await Fetch.create(
"/api/frameworks/userrunstatus/by/" + userId.userId,
frameworkUserRunStatus,
credentials
);
console.log("api-constructAssociation - response = ", response);
return await response;
I was expecting to have a request object (options or params) that I could read the, frameworkUserRunStatus object, on the server side but I could not. What is the object that I read in the controller on server side?
const create = async (req, res) => {
console.log("Server Side - frameworkUserRunStatus.controller - create start ");
console.log(
"Server Side - frameworkUserRunStatus.controller - inside try create after start, req.params = ",
req.params
);
/*
console.log(
"Server Side - frameworkUserRunStatus.controller - inside try create after start, req.options.body = ",
req.options.body
);
console.log(
"Server Side - frameworkUserRunStatus.controller - inside try create after start, req.options.json()= ",
req.options.json()
);
*/
const newFrameworkUserRunStatus = new FrameworkUserRunStatus({
})
I think it'd be useful to include in the Error handler the actual error message returned by the api (on
response.status !== 200
) 😉I would have prefered the
objectToQueryString
to be included in the fetch library...Hello, can you explain how I could upload an avatar image associated with json data?
There may be cases where the form can contain an avatar, such as a user form, and there can be cases where the form can only contain data without an avatar.
create,
read,
update,
delete
instead of
get,
create,
update,
remove
Read is a great alternative instead of get. Unfortunately, "delete" is a reserved keyword in JavaScript.
I do it similarly on my daily job.
Simplified structure:
book/
create
read
update
delete
books/
available
availableByType
specific
Oh I see. Yes, that's a good solution too. Thanks for sharing.