Is the English language a standard to describe a Webservice (Rest, SOAP Etc.)?

Question

In the current project where I'm working on, we had a discussion about the language (English or Spanish) we should use to describe pathnames, fields, payloads, Etc.

I thought this was an easy topic, however, I couldn't find an accurate source where is described that English should be the standard for describing Webservice's components.

For example, assume we have a Rest API very simple with CRUD for creating Users

English

POST /v1/users

GET /v1/users/{uid}

DELETE /v1/users/{uid}

PUT /v1/users/{uid}

Spanish

POST /v1/usuarios

GET /v1/usuarios/{uid}

DELETE /v1/usuarios/{uid}

PUT /v1/usuarios/{uid}

I think this is not a problem, however, I want to understand if I need to follow a standard or if it doesn't matter which language I use for describing Webservice's components.

Probably, this is a primarily opinion-based question, if you think it is, please just address me with a comment.

Answer 1

Being an Spanish native speaker myself, I see no technical justification to write an API in anything other than English, the de-facto technical language.

If the intention is to develop an API that is intractable to anyone outside of the Spanish-speaking world, I guess this would be the way to go.

Yet, I see this happens again and again among Spanish-speaking software projects. I think it is detrimental.

OTH, let us look at Rakuten, one of the most powerful tech companies in Japan. Rakuten decided to enforce English as the working language for all employees, even though the bulk of its business is in Japan.

It tells you something. In the globally connected 21st century world, aim your products for the widest audiences.

I cannot conjure an axiomatic reason to do so (in the way I would say "do not use goto statements.") But writing something in anything other than English is something I would not do.

Answer 2

I don't think there's a norm, but I'd simply say : there could be lots of way your code can be used by people with other language. So, sticking to english is the better way to let it understandable and usable by anybody.

Answer 3

I'm a native bilingual Spanish-English speaker living and working in Spain. In many of my IT software development projects I find myself working in international teams collaborating with people in India, France and UK. In these scenarios it's sensible to be understood in a language common to all. On the other hand I've also worked on projects where the client only spoke a regional language and there was no need to use neither Spanish nor English. It really depends who your colleagues are and who your end-users are.

Answer 4

Using another language as English always enforces you to replace the special characters of your language, like accents and ñ and stuff like that. But that is solvable.

The question is: Who is going to use your service? If the consumers are non-Spanish speakers, they definitely appreciate English.

However, in my experience you often have very domain-specific names, that sometimes can't be translated properly into English or it is hard to know what the right word in English would be as translators often give you weird translations for your domain specific (Spanish) words. So I saw many Webservices that were translated into English but I still had to ask: What does that mean? because the translation just didn't make sense.

Therefore my opinion is to use Spanish, unless your Webservice is actually consumed outside the Spanish speaking world. Because if it is consumed outside the Spanish speaking word, a good translation is available too.

Answer 5

I am a German native speaker and my working language is mostly English (working for a US company), definitely when it comes to coding. I basically have all my professional software set to English as well, and I even have to say that I'm getting confused when I see it in German ;-) So my point is, that from my daily routine point of view I wouldn't even consider using my native language for coding.

However, on a more general level, I would want to argue that an API should be created in such way that the consumer can easily tell from the endpoint naming what it is supposed to do. So as some others stated above, I think it is worthwhile thinking about who is the consumer eventually. If you have a closed target audience, all speaking the same language, no plans to expose the API externally, then I could well imagine to make the endpoint labels in that language.

Two more points worth considering: - Can you be sure that also all (future) developers speak that language and it should not be confusing to them? - What about providing the API endpoints with labels in both languages? Depending on the programming language / framework you use, I think it could be quite simple to duplicate the endpoints, yet, calling the same logic. I'm not sure this is good practice, but if there's a benefit to the consumers, and you'd still like to stick to the working language to be on the safe side, I could imagine this.

Answer 6

I think if your team (and future developers in your project/company) and client are Spanish speakers you could use English or Spanish as you want. But if you think in any moment a non-Spanish speaker will code or use your API, you should use English.