When I advise clients on how to work with APIs, I recommend never calling API's directly.
Instead, I suggest creating functions whose sole purpose is to get and set API data. It allows you to change the API endpoint and even how your API returns data without having to rewrite significant portions of your code base.
Let's dig in!
An example
Let's imagine you have a todo app.
Users can view a list of their todo items, add new items, and mark items as complete. Each of these actions makes a call to an API that gets, sets, or modifies data.
Let's say the API endpoint is /todos.
A GET request returns all of the data, a POST request creates a new todo, and a PUT request updates an existing todo item.
// Data returns from GET let data = [{ id: 1234 todo: 'Play D&D', completed: false }, { id: 5678 todo: 'Buy milk', complete: true }]; // Data format for POST and PUT methods let update = { id: 1234 todo: 'Play D&D', completed: true };
Direct-use endpoints
I sometimes see API endpoints called directly in the code that uses their data.
async function renderTodos () { // Get the API data let request = await fetch('/todos'); let todos = await request.json(); // Render the data let app = document.querySelector('#app'); app.innerHTML = `<ul> ${todos.map((todo) => { return `<li>${todo}</li>`; }).join('')} </ul>`; }
This works just fine… until it doesn't.
APIs change
There's a good chance your app calls the API in various places for various tasks. When the API changes, that means a lot of rewrites.
Maybe the endpoint changes from /todos to /api/v2/todos. A simple enough change, but potentially scattered across different files.
Maybe the way authentication is handled changes. Now you need to update your fetch() request everywhere it's used.
Sometimes, the data that's returned changes.
// The original GET response let data = [{ id: 1234 todo: 'Play D&D', completed: false }, { id: 5678 todo: 'Buy milk', complete: true }]; // The new GET response let newData = { 1234: { todo: 'Play D&D', completed: false }, 5678: { todo: 'Buy milk', complete: true } };
Now, anywhere your API is called, you need to not just update the API call, but refactor how you work with it.
But there's an easier way.
Getter and setter methods
I recommend my clients use dedicated methods for calling APIs and processing the data that's returned.
// Get the API data async function getTodos () { let request = await fetch('/todos'); let todos = await request.json(); return todos; } // Render todo data async function renderTodos () { let todos = await getTodos(); let app = document.querySelector('#app'); app.innerHTML = `<ul> ${todos.map((todo) => { return `<li>${todo}</li>`; }).join('')} </ul>`; }
If the API changes, you now have a single file where you can make your changes.
And for more severe changes, like a big change in how the data is returned, you can transform it before returning it and avoid ever having to update the functions that use it at all.
// Get the API data async function getTodos () { // Get API data let request = await fetch('/todos'); let todos = await request.json(); // Transform the data into the old format let transformed = Object.entries(todos).map(([id, item]) => { let {todo, completed} = item; return {id, todo, completed}; }); // Return the transformed data return transformed; }
With this approach, renderTodos() and any other function that uses the output of getTodos() doesn't need to change.
The specifics of the API become an implementation detail you abstract away.
If you or your team need help structuring code for long term maintenance and scalability, get in touch. I'd love to help!
Cheers,
Chris
Want to share this with others or read it later? View it in a browser.
0 Komentar untuk "[Go Make Things] Data portability: API getter and setter methods"