The Ultimate GET Endpoint

There are several API types ie REST, Grapghql and SOAP. REST and Graphql APIs are widely used.

The main difference between the two is that Rest API requires different API endpoints for individual action i.e https://api_url/login and https://api-url/register meanwhile graphql API can use only one endpoint for both actions.

Rest API uses different methods for its CRUD operations such as:-

1. GET - for fetching data
2. POST - for creating data
3. PUT - for updating data
4. DELETE - for deleting data

Graphql uses mainly two resolvers:

1. Query - for fetching data
2. Mutation - for creating, updating or deleting data

There are other differences but one similarity is that while rest API uses get method to fetch data, graphql uses query to fetch data. This blog is mainly focused on get/query an API endpoint.

The GET http method is a powerful method for getting data from your server. It’s an easy way to get information from the server, and it’s one of the most common endpoints used in APIs. GET allows you to make any number of calls.

Issues that might be a result of ill-formed GET endpoints

1. There are multiple data formats that can be transferred via http requests such as JSON, XML and HTML. Some of these formats such as XML are outdated and andpoints that return those formats may cause extra work while decoding/encoding the response.

2. In most applications there are different access levels, Ill-formatted endpoint will cause any user to access data that are meant to be accessed by a special group of users such as admins

3. For endpoints without pagination a single request could return a thousands or millions of data that may cause some traffic issues and/or issues on the browser ie loading time for request to complete and large amount of data used in a single request

4. A single response can have multiple fields whether data is returned as an object or array of objects. These fields count can vary from 1 any number. Fetching these data if there are many explicit filters can cause issues similar to the issues mentioned in the previous item. Graphql was made to solve this problem as the client will be required to pass the fields they want to fetch. REST endpoint doesn’t have this feature out of the box, it's up to an API creator to integrate this in their code.

5. An API without filtering and sorting will force users to view all data and scroll to view what they want where users might want to fetch only the latest/oldest data or data with a certain value in a certain.

Qualities that will make your GET endpoints better.

1. JSON format response
   
   JSON format is the standard data format that is accepted by any technology. Most technologies have built-in methods to decode and encode JSON data.
   This can easily be achieved by setting Content-Type application/json in the headers request headers.

2. Roles Accessed (Used by admin & normal users)
   
   Most applications have normal user views and admin views for the same kind of data. While normal users should be able to view data related to them, admins should be able to view all data. Get endpoint should have guards for details that will be viewed by an admin so they won't be available to normal users

3. Pagination
   
   Pagination is a sequence of pages which are connected and have similar content ( Learn more )
   Pagination is widely used when there is a large amount of data that can not be presented on a single page.
   Pagination improves user experience and solves issues including traffic issues and loading time for a large amount of data.

   There are different pagination implementations. Here I will cover two types.

   3.1. Offset pagination using limit/page-size and skip/page
   
   Limit or page-size defines the number of data that will be returned on every request meanwhile skip/page defines where should the fetching begin.
   
   Let's assume we have 30 items in our database, and query data with page-size of 5 items. When skip/page = 0 i.e /users?limit=5&skip=0, it will fetch from first data to 5th data, on another query data will be fetched from 6th to 10th data i.e /users?limit=5&skip=5 and so on. This is well formatted and changing the page size affects the whole flow of data. It’s easier to use number pagination on the frontend using this type

   3.2. Seek pagination using a certain unique value and limit/page-size
   
   The unique value defines the value of the last item fetched so that we can fetch the next item as a starting point and the limit defines the number of items that will be returned on every request.
   
   As long as we have our last fetched item we can change the limit and still it won't affect the way the data are queried.
   This isn’t suitable for number pagination on the client side of the app, rather the infinite scroll.
   
   For instance /users?limit=5&lastQueriedId={userId}, this will allow users to pass any page size without affecting the data that are coming in.

4. Backend (Explicitly) Filter
   
   The GET should allow users to filter and select the data they want to see. You can use this endpoint to fetch specific fields, or all fields in a single request. Here are some examples of how we’ve used this feature:
   /users?fields=first_name,last_name - this should return data with only first_name and last_name fields.

5. Latest Sorted
   
   For the array-like response response will make much sense if ordered from latest data to oldest data except for some scenarios such as getting data in a certain pattern i.e twitter feeds.

6. Allow filtering data by fields
   
   Filtering data by fields is a common practice which allows users to filter their results based on the values of any of the fields in their requests. The GetEndpoint should allow filtering by any field. For example filtering data with date, name and email fields:
   /users?filter=date:eq:12-10-2021,name:eq:ben,email:eq:mailto:email@example .com,
   This should return users with either of the field values passed as parameters.

7. Allow sorting by date, number or alphabetical order
   
   Sort by date: an endpoint should allow sorting data by the date they were created. This is especially helpful if there is a large amount of data and want to scan through them easily.

   Sort by number: If there is a large amount of data, it might be helpful to allow sorting the data based on their number fields such as amount field/column on the database so that they're easier to find in the list.

   Sort alphabetically: an endpoint should allow sorting data fields/columns by alphabetical order ascending/descending.

8. Logical nesting on endpoints name
   
   The first step is to create a logical nesting on your endpoints. This will allow you to organize your endpoint names in a way that makes sense and makes it easier for users to find the information they need when working with them.

   For instance you have an endpoint called /users which is used to fetch all users, an endpoint for fetching a single user should be /users/{userId} and if there is another endpoint to get a specific detail about that user for instance messages you can name your endpoint as /users/{userId}/messages

Hope you will find this article helpful. Follow our tech blog ClickPesa blog, where the team shares stories about our development process improvement journey, tips, among other things. Happy Hacking!!