Disclaimer: In pure REST, API's are opaque and the URL should be whatever what was sent as a link in the response to a previous request. But, I'm not talking pure REST, I'm talking more pragmatic APIs which involve some concepts from REST and as well as general API best practices.
When writing an API, it starts simple. You identify the obvious resources and end up with endpoints such as:
Eventually, your API will have to capture more sophisticated concepts and model more complex resources that cannot be expressed in short single nouns. Some real world examples include:
In Kebab Case, the individual words are separated by hyphens. Ice cream is expressed as ice-cream. This approach is used in the Lisp programming language, in lots of URLs (for example, every blog post in www.blogger.com e.g. http://dublintech.blogspot.com/2018/08/oauth-20-authorisation-code-grant.html). The observant amongst you will note sometimes the word "dash" is sometimes used in technical references instead of "hyphen". So, what's the difference? In English grammar, hyphen is the thing used to join two words to make one whereas the dash is the thing used to usually add some sort stylistic emphasis to the end of a sentence such as: "I might have an interesting point here - you never know".
In this approach, an underscore is used to separate words. Ice cream becomes ice_cream. This approach is used in Python and Ruby for anything other than a class name or static constant.
Google
The Github API is a good example where we get a reminder that if possible, you should try to avoid this issue by trying to avoid compound nouns as it avoids them by using some creative name spacing.
However, some more rooting around and you'll find a compound noun such as check run expressed using kebab case in the URL and he JSON body using snake case.
Twitter
Facebook
Facebook's Graph API tends to avoid resource naming in URLs and in JSON bodies it is snake case.
By this stage, you should be getting a little but confused. So let's recap via the table below.
When writing an API, it starts simple. You identify the obvious resources and end up with endpoints such as:
/api.mycompany.com/tweet
Eventually, your API will have to capture more sophisticated concepts and model more complex resources that cannot be expressed in short single nouns. Some real world examples include:
- Enabling request validation via a Request Validator resource (AWS API Gateway API)
- Performing a customer search via a Customer Search resource (Google Customer Search API)
- Running powerful checks against code via a Check Runs resource (Github API)
In English grammar, nouns that are really two nouns joined in some way are called compound nouns and in English grammar, compound nouns follow one of three patterns:
- All the one word: haircut, toothpaste
- Two words: rain forest, ice cream
- Hyphenated: self-esteem, brother-in-law
In the API world there are different options to choose from but it is better for consistency that your APIs just pick one approach and stick to that it. So firstly, what are the options for compound nouns from an API perspective?
Camel Case
Camel case is the practise of writing each word in the phrase with a capital letter. There are two variations:
- Initial upper case (also know as Pascal's case) is where the first letter is also a capital, for example: IceCream. Pascal's case is popular in programming languages for naming classes e.g. Java.
- Initial lower case is where the initial letter is always lower case, for example: iceCream. This approach is popular in programming languages (again Java is a good example) for naming variables. When people say camel case, they are usually referring to the initial lower case format.
Kebab Case
In programming we don't care whether the term is hyphen and dash. They are used interchangeably and mean the same thing.
The kebab case approach became popular in Web URIs because search engines knew that the hyphen meant separate words and could index the URI properly. This convention used by search engines meant hyphens became a de facto standard for URIs.
The kebab case approach became popular in Web URIs because search engines knew that the hyphen meant separate words and could index the URI properly. This convention used by search engines meant hyphens became a de facto standard for URIs.
Snake Case
Join words
In this approach the words are just joined. There is no -, no _ and no capitalisation of anything. This is not a popular approach with developers because it's difficult to read.
APIs
Should we use camelCase, kebab-case or snake_case in an API? Well unfortunately, Mr. Fielding's dissertation did not go into such detail. So what are people actually doing? And is the approach used consistent across the API's URL and the JSON Body. Let's take a look.
AWS
AWS have different API styles for different services. The API Gateway REST API reference shows that JSON payload uses camel case but the URL uses nothing, it's just:
/restapis/{id}/requestvalidators/{requestvalidatorId}
Surprise, surprise Google also have lots of APIs. The Google
Custom Search API is similar to the AWS API Gateway API. The compound noun in the URL is just the one word and the JSON body is camel case.
The Google Gmail API has camel case in request body and in some URLs, for example the forwarding addresses API.
The Google youtube API sometimes will use kebab case in the URL e.g. yt-analytics but in other cases will use single word e.g. youtubepartner. But the JSON payload is camel case.
Github
However, some more rooting around and you'll find a compound noun such as check run expressed using kebab case in the URL and he JSON body using snake case.
Stripe
Stripe use snake case in the URL and in the JSON body. For example the PaymentsIntents API.
https://api.stripe.com/v1/payment_intents
and JSON body...
{
"id": "pi_Aabcxyz01aDfoo",
"object": "payment_intent",
"allowed_source_types": [
"card"
],
"amount": 1099,
"amount_capturable": 1000,Paypal
Paypal have more compound nouns than the other APIs checked. APIs for resources such as billing agreement the API will use kebab case in the URL but then use snake case in the JSON payloads.
Twitter use snake case in the URL e.g. /saved_searches/ and snake case in the JSON payloads.
By this stage, you should be getting a little but confused. So let's recap via the table below.
| API | URL | JSON Body | |
|---|---|---|---|
| AWS API Gateway | No separator | camelCase | |
| Facebook Graph API | N/A | snake_case | |
| Github | Snake and Kebab | snake_case | |
| Google custom search | No separator | camelCase | |
| Google Gmail | camelCase | camelCase | |
| camelCase | camelCase | ||
| Pay pal | kebab-case | snake_case | |
| Stripe | snake_case | snake_case | |
| snake_case | snake_case |
Everyone is different, what should I do?
So there is a lack of consistency across the industry. However there are point worth making:
Until the next time, take care of yourselves.
- In general compound nouns are best avoided. In all the APIs checked (except PayPal), they appear in under 5% of the APIs. This means developers don't get upset when their favourite approach is not used.
- The only Web API in the selection above that had more than 5% of its APIs using compound nouns was PayPal and they went for kebab-case in URIs.
- kebab-case is never used in any JSON body. The syntax is allowed. So what drives this trend? It's more than likely because JavaScript Web UIs are possibly the mos popular client invoking API and the similarly the most popular back end language serving the API is Java and both of those dudes don't allow the - in any of their declarations.
Is there anyone else saying anything?
In the excellent REST API Design Cookbook, industry expert Mark Masse suggests:
- Make your APIs lower case, which rules out camel case
- Use kebab case when expressing compound terms in your URIs
- Avoid using underscores as they may not display well since some browser render hyperlinks with an underline added
Make a decision
- Avoid compound nouns if you can. This isn't always possible. Sticking to a ubiquitous language is important and helpful. If you have a complex business application you will have lots of compound nouns.
- If you can't avoid compound nounds and more than 5% of the APIs are going to involve compound nouns use kebab case for your URIs. Why? Because if you have a complex business domain it's not only developers you need to think about. Lots of BA's, Product Architects, curious Managers will also be looking at your APIs. Kebab-case is the easiest to read for everyone.
- For JSON body, I think it is okay to use camelCase because this is the easiest to map back to JavaScript and Java code. It is also a recommendation from Google to use camelCase in JSON.
- If you have to use camelCase in your URI's, consider using the first letter capital approach for the URIs as the URIs are supposed to marking resources not attributes. Resources are more analogous to Java Classes which also use initial letter capital format; whereas the JSON payload attributes are analogous to Java attributes which use initial lower case.
