Questions about how to name an API when the number of APIs increases

Asked 2 months ago, Updated 2 months ago, 6 views

Currently, in my company, the API names are api1, api2, api3, and so on.
When calling api, it's like api/v1/api1.
I don't know what api is going to do with this.

There are two reasons why I chose this name.
·In the past, when the number of api became huge, it became difficult to name each appropriate name.
·When updating a child table element in a program to be updated, I can't think of an appropriate name.

For the above two reasons, creating an api under the name api{n} has become a culture in my company.

Also, because there are no restrictions on creating APIs, members are different depending on the person who makes the API, even if the get method is correct.

So I'm thinking about how I can improve maintenance and how to create a RESTful API.
When I consulted with my boss, he said he decided to make an api under the name api{n}.

I looked into various things, but I've never heard of a case of making it the same as ours, and it didn't come out when I looked it up.

In fact, there are many services that are larger than ours and have more APIs than ours.
"Of course, there is also the problem of ""the number of api has become huge and it is difficult to name each one properly."""

I would like to know how it is resolved, how to design the API to avoid the above problems, and how to build it with a RESTful API.

ruby-on-rails api rest

2022-09-30 14:19

5 Answers

In Japanese companies, it is difficult to name according to the naming convention.There are not many cases where English names are attached to paperwork or business forms, so it is quite difficult to give English names when you do programs.

Wikipedia's Naming Conventions (Programming) page describes the business value of naming conventions as follows:

While end users are rarely aware of the good or bad identifiers, successful identifiers make it extremely easy for successive analysts and developers to understand what the system is doing and to determine how to modify and expand source code as new business demands occur.

For example,

a=b*c

The code is not grammatically incorrect, but I have no idea what it means or what it means.

In contrast,

weekly_pay=hours_worked*pay_rate

The code at least understands the meaning and intentions of the application (weekly_pay = weekly, hours_worked = working hours, pay_rate = hourly).

I understand this very well, but the naming convention says that using kanji is not a good idea, so it is absolutely necessary to translate it into English and name it.There is also a way to write in romaji, but unlike kanji, the meaning is not easily understood and it becomes longer.As a result, "identifiers" are not the words you usually use, so the advantages of helping you understand them are reduced, and people who don't understand English often translate them into unintelligible English.

This time, it's a naming convention issue for API, but it's the same issue with CMS and blogging about URL.In foreign countries, there are many cases where the title name is attached to the end of the URL, but if you do that on a Japanese website, it becomes a Japanese URL.If you don't like using Japanese URLs, it's a lot of trouble to think about English titles and users don't search in English, so it doesn't work, so you often use id.

In the end, it is a problem to bring the naming conventions made in English-speaking countries directly to Japan, and I think we have no choice but to make a decision based on the international level of the company and the person in charge.In many pure Japanese companies, it is easier to understand if the name <initial letter>+ serial number is left behind.


2022-09-30 14:19

I don't think abbreviations, coined words, or symbols should be used to improve maintenance.
I would like to name it separately by words such as cameraCase, snake_case, kebab-case, etc.
How about a prefix if you don't want to completely break down the current rules?
Can't you manage with prefix + naming?

Why don't you look at the API name and not understand the outline of the function?


2022-09-30 14:19

Even if it's difficult to name everything unique, try classifying it by general function.
Try the prefix + serial number and so on.
If possible, you can organize it little by little by preparing a means to access it under another name while keeping the names of the past.


2022-09-30 14:19

It's hard to name.
Sorry it's not directly with the API, but
nameings such as <initial letter>+ consecutive 5 digit numbers as specified are
It seems to be used a lot in older systems.I think it was a remnant of a time when the name space was small and it was difficult to give a unique name.
So it's normal to say, "Do you exist as a name?"
If you use such a system, it may be difficult for some people to change their names to modern names because they have a complete understanding of their functions with initials and serial numbers.

That's all for your information.


2022-09-30 14:19

First of all, I think it is much more important to have a solid document and source code than naming.At a minimum, you can obtain detailed descriptions of features and operations.
Designing and developing means creating functions in an environment where the overall picture is not visible, so I think it is useless to stick to appropriate naming in α and 版 versions under such circumstances.
If you have managed the database before, please think carefully.The name in the API is equivalent to what we call an ID in the database, and the ID is either an automatic serial number or a hash value, right?You may hesitate to specify an artificial value in the ID.(Because it means that ID management is done manually, not by the machine)
If you know something called a lambda function, please think about it carefully.Why is the lambda function convenient?Because there is no need to name it and no need to be managed by humans.
The API naming can be used at most about a dozen characters.Therefore, it is impossible to explain the function in detail.
The first thing that naming requires is who uses the API, what implicit (prerequisite) knowledge the user has, and what kind of information they don't have to write.
Second, clarify where each API stands (hierarchical structure) in the overall API view, how each API does its part, and how APIs differ from one another to facilitate retrieval.
Third, use words so that the API's name remains unchanged as much as possible.
I think naming in the API means building a human interface even if you give up mechanical management, so if you don't meet these three requirements at least, naming doesn't make sense.


2022-09-30 14:19

If you have any answers or tips


© 2022 OneMinuteCode. All rights reserved.