by Tony Harris • 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.
Sign up for our free 14 day hosted trial to learn how.
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:
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.
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.
For more information about best practices for naming API endpoints, read our article here.
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.
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.
Also known as UpperCamelCase, this is like camelCase except the first letters are capitalized.
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.
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!
Join the DreamFactory newsletter list.