Spencer Nguyen - April 6, 2021
When you write code, you learn quickly that it can be an exacting process. Spaces and semicolons mean something very different to a computer than they do to us. So what’s the best way to document your API in a way that both humans and machines understand? For starters, here are some practices for naming your API endpoints.
What Are Endpoints?
An application programming interface (API) is a piece of software that connects to different programs. There are specific locations that the API accesses to send and receive data. These connection locations are called endpoints. API requests will contain a header, HTTP method, headers, and body.
Programs can have multiple endpoints. As an example, Instagram uses the following endpoints in its API:
- One to gather data on interactions (likes, follows, replies)
- One for moderating comments and replies
- And one for discovering hashtagged media.
Why Good Naming Practices Are Important
We’ve said before that your API is only as good as its documentation. Making your documentation easier to read by third parties is part of the API building process. Knowing how to name your endpoints is part of creating clear API documentation. This is no place for freestyling; stick to what developers already know and expect, and they’ll be more inclined to work with your API.
Why would you want someone playing around with your API? If you’ve released an open API, that means you’re opening the door for others to add some innovative functionalities. Facebook’s API is a common example of this. If you’ve ever been to a website that invited you to login with your Facebook credentials, they did so with Facebook’s public API.
It’s also important to remember that developers aren’t the only ones looking at your API design. You’ll also want to improve readability and make the documentation accessible to the decision makers in management and curious amateurs. In other words, these are people who may not be as familiar with coding.
And in the event that you do need API support, making documentation clear and easy to read will help with debugging the code. Best practices for naming API endpoints apply to any programming language you want to work with, from XML to JavaScript to python.
Some Best Practices
If you have any prior experience with coding, some of these practices may feel like second nature to you. Here’s a list of a few tips for naming API endpoints.
- Use American English when choosing resource names. Most of your audience will be familiar with this dialect. There are exceptions here if you want to target specific audiences. But for the most part, American English will have a wider reach.
- Avoid using industry-specific jargon. If you must use terms at times, include support documentation that explains its usage.
- Use lowercase letters most of the time. See below for more details.
- Using plural nouns to name API resources is the norm. But if you choose not to do this, be consistent. Don’t make some resources plural and some singular.
- Don’t abbreviate names. Example: use “phone_number” instead of “tel_no.” This will spare developers from wondering what your shorthand means.
- Don’t include file extensions in names.
- Standard punctuation use is forward slashes to denote hierarchy (files/documents/client_list) and a comma or semicolon for lists. Don’t end with a trailing forward slash.
For more information about best practices for naming API endpoints, read our article here.
Some Naming Conventions
Code typically makes use of lowercase letters the majority of the time. But this can be difficult to read, especially for someone not familiar with your API. Developers have a few ways around this problem to make code easier on the human eye.
camelCase
You may also see this called “dromedary case” or “lowerCamelCase.” The capitalization of camelCase gives a hint at its style. The first letters of each compound word are capitalized except for the first word. This makes the name’s compound nature more visible and easier to read by humans.
PascalCase
Also known as UpperCamelCase, this is like camelCase except the first letters are capitalized.
snake_case
A common sight when coding in C languages, snake_case doesn’t use capitalization or word compounding at all. You simply type all letters in lowercase with an underscore (_) taking the place of spaces. Again, the spelling of this case is an illustration of its style.
Turning To DreamFactory
These conventions may be intimidating to you, especially if you’re not familiar with code. Fortunately, DreamFactory has an API solution. We can build a full-featured, documented, and secure REST API in minutes for you, so you don’t have to write a single line of code or find the best way to name your resources. But if you do want to try your hand at code, we also have resources, tutorials, and templates available to walk you through each step. Our server-side scripting supports NodeJS, PHP, Python, and V8JS.
Ready to get started? Sign up for our free 14-day trial and do a guided tour of the API creation process today!
As a seasoned content moderator with a keen eye for detail and a passion for upholding the highest standards of quality and integrity in all of their work, Spencer Nguyen brings a professional yet empathetic approach to every task.