Improve your API design by following this simple step

Improve your API design by following this simple step

We will brainstorm 11 names for the GET endpoint and look which one is the best fit for our example. We will also document our decision.

Recently my department went through a transition from 5 to 25 software engineers. This brought many challenges, including building consistent REST API across different teams. To improve it, we’ve put up together a REST Resource Naming Guide.

REST Resource Naming Guide

The naming guide is a set of rules on how to choose a good name for an endpoint. As you go with development — it will contain more and more rules. Each rule ideally is discussed within your company. It can be hosted in Confluence, GitHub wiki or even in your source code.

Starting point

Representational state transfer (REST) is a software architectural style for creating Web services. As part of this style, your application has a state(resource). To alter the state of your application, you expose certain actions (endpoints). Endpoints should make use of HTTP verbs: GET, POST, PATCH etc.

Web application example

Bookstore is a web application that allows to manage a library of books via REST API. In this article we will add a GET endpoint to allow us to read the list of books. We will start with brainstorming all possible names for the endpoint and then we will refine this list until we have only one name left.

Brainstorm all possible names

Let’s brainstorm all the possible names that we can pick for our GET endpoint. It will be used to return all books from the Bookstore. This is a list of possible names that I came up with:

GET: /books/
GET: /book/
GET: /book/all/
GET: /books/all/
GET: /books
GET: /book/all
GET: /books/all
GET: /book
GET: /getBooks
GET: /getBooks/
GET: /book/get/

They are all legit names, but not all of them fit the REST paradigm.

get-request api rest-api rest api-development

Bootstrap 5 Complete Course with Examples

Bootstrap 5 Tutorial - Bootstrap 5 Crash Course for Beginners

Nest.JS Tutorial for Beginners

Hello Vue 3: A First Look at Vue 3 and the Composition API

Building a simple Applications with Vue 3

Deno Crash Course: Explore Deno and Create a full REST API with Deno

How to Build a Real-time Chat App with Deno and WebSockets

Convert HTML to Markdown Online

HTML entity encoder decoder Online

A Simple Guide to API Development Tools

APIs can be as simple as 1 endpoint for use by 100s of users or as complex as the AWS APIs with 1000s of endpoints and 100s of thousands of users. Building them can mean spending a couple of hours using a low-code platform or months of work using a multitude of tools. Hosting them can be as simple as using one platform that does everything we need or as complex as setting up and managing ingress control, security, caching, failover, metrics, scaling.

What is REST API? An Overview | Liquid Web

What is REST? The REST acronym is defined as a “REpresentational State Transfer” and is designed to take advantage of existing HTTP protocols when used

Consume Web API Get method in ASP NET MVC | Calling Web API | Rest API Bangla Tutorial

LIKE | COMMENT | SHARE | SUBSCRIBE In this tutorial, I will discussed about How to Consume Web API Get method in ASP NET MVC. Blog : http://aspdotnetexplorer...

A Simple Guide to Planning API Roadmaps

APIs - the current “big thing” - offer the opportunity for modern organizations to unlock new and lucrative business models. The article below covers some tips on how to spin the API flywheel and leverage its possibilities. 

Consume Web API Post method in ASP NET MVC | Calling Web API | Rest API Bangla Tutorial

LIKE | COMMENT | SHARE | SUBSCRIBE In this tutorial, I will discussed about how to consume Web API Get method and display records in the ASP.NET View. Here, ...