renaming n-api to something more appropriate and descriptive

[jasnell]

N-API is a poorly selected name for the ABI-stable API for native addons. While the intent is for the name to be pronounced "En-Ay-Pee-Eye", it is most often colloquially reduced to "nappy", which -- if you're unfamiliar -- is term often used in English as a derogatory way describing the hair of black people. Aside from that, it's just not actually descriptive of what the API is for.

I'd like to propose "Stable ABI" (or S-ABI for short) as an alternative. (@addaleax has suggested C-API as a viable alternative also... based on the fact that, well, "that's exactly what it is" 🤣... that would work also)

I can open a PR to update all of the references in project but wanted to determine the support. I'd rather not spend a ton of time bike-shedding alternative names.

There's been some adoption of the API in other projects so the old name certainly won't disappear entirely overnight, but renaming it here would be a great step in the right direction.

/cc @addaleax @nodejs/tsc

[jasnell]

Let's make it a vote with emoji. 🎉 = S-ABI 🚀 = C-API 👎🏻 = status quo

[Trott]

@nodejs/n-api

[mhdawson]

Will put on agenda of the N-API team for this Friday.

[mhdawson]

@jasnell, the files in src are node_api.h, node_api_types.h and despite being a bit longer it would likely be less confusing/more consistent to rename doc references to node_api or node-api than using C-API or S-API.

[gabrielschulhof]

@mhdawson we have js_native_api.h for non-Node.js-specific APIs, so we could diverge this further into node_api_* and js_api_*.

[mhdawson]

@gabrielschulhof I'm not quite sure I follow. The discussion is around replacing N-API in all of the docs with something else. I'm suggesting we use NODE-API to replace N-API versus the other suggestions based on the names of the include files.

[gengjiawen]

n-api has been Node.js brand for a long time. Search engine, books, library author used it everywhere. It can have two names, but rename it will cost too much for community.

[mhdawson]

From the discussion in the team meeting,

1. @jasnell were you suggesting that it would change all of the API call names (for example napi_create_buffer) as due to the ABI stability promises we cannot remove the existing symbols, they would have to be duplicated. Adding duplicate symbols could double the code space (if we inline common implementation) or slow things down requiring and additional call for every method. The other complication is that methods that used the new symbols would not run on older Node.js versions. This would mean that the new aliases would all have to be added as part of a new node api version.

2. in terms of naming from the discussion if there is a rename we'd prefer node_api overall, and then for the new method names we would use node_api_xxxx for node specific methods and js_api_xxx for the non-node specific methods. That would also avoid duplicates of the existing include files (src/node_api.h, src/node_api_types.h)

3. The team does share the concern about the issue related breaking existing content, blog posts etc. We will continue the discussion in the next meeting based on your answer to question 1).

[jasnell]

No, not suggesting we rename or duplicate symbols, just do better as we go for ward from here. node_api works good as a name.

[mhdawson]

@jasnell it sounds like what we might be able to do is:

• Make sure that when we talk about the API going forward we use NODE-API instead of N-API, do a careful pass through docs and use that where it won't cause broken links for existing references etc.
• Leave all methods, symbols etc as they are, while the goal of the steps from more consistently referring to the API as NODE-API leading to people thinking node api when they see napi or n-api.

@jasnell would that align with how you were thinking we'd address the concern?

[addaleax]

were you suggesting that it would change all of the API call names (for example napi_create_buffer) as due to the ABI stability promises we cannot remove the existing symbols, they would have to be duplicated. Adding duplicate symbols could double the code space (if we inline common implementation) or slow things down requiring and additional call for every method. The other complication is that methods that used the new symbols would not run on older Node.js versions. This would mean that the new aliases would all have to be added as part of a new node api version.

Fwiw, these are all problems that can be easily solved by using #define.

[mhdawson]

@addaleax using define was something that we discussed, from our understanding it can solve the names in the include files etc. but still leaves the symbols with the original names as what is exported by node. It would be another possibility for "partial" replacement but we wanted to understand what/how far @jasnell was suggesting we go before considering the different partial/full steps.

[jasnell]

@mhdawson ... Yes, that sounds good. Using the #define approach for aliases would be ideal, I think.

[jschlight]

@mhdawson Since the N-API team has decided to move forward with this initiative, does it make sense to create a new issue on https://github.com/nodejs/abi-stable-node and organize our work there instead of continuing this issue? We could just rename #417 and pickup from there.

[mhdawson]

If @jasnell is ok with it I can just move this issue over to the abi-stable-node repo ?

[jasnell]

Go for it

[jschlight]

As we are moving forward with this initiative, I thought I'd collect some ideas for further discussion and planning by the N-API team and others. Here are some aspects we need to consider:

• Have we decided on NODE-API as the new name? - YES
• What is our pattern for naming new symbols? - use node_api_ instead of napi_ to prefix new symbols
• What is our approach for existing symbols? - leave as is
• What locations of the Node.js core documentation need to be updated? - update wherever possible
• What locations of ancillary repositories like node-addon-api need to be updated? - the others repos this team manages (node-addon-api, node-addon-examples, new headers repo)
• What related projects such as node-gyp, node-pre-gyp, etc. need to be updated? - Jim will add comment on this issue were docs may need to be updated.
• How will these updates be accomplished? - We can PR them?
• What sort of outreach to the wider Node community do we need to make and what is our message?
  • plan is to frame as "clarification of what was already the name", hopefully does not need much messaging/clarification.

[gabrielschulhof]

At today's TSC meeting we concluded that, for the time being, we will replace documentation references to N-API with Node-API, stopping short of providing C preprocessor aliases for our symbols and public macros. We may make deeper changes if, after these changes, we feel that further changes are warranted.

[jschlight]

These are projects that facilitate the building of Node-API modules. Some of them include documentation that refers to N-API.

Docs

• N-API resource - http://nodejs.github.io/node-addon-examples/
• node-addon-api - https://github.com/nodejs/node-addon-api

Related Node-API Build Tools

• node-gyp – Documentation does not refer to N-API.
• CMake.js – PR submitted
• node-pre-gyp – PR landed
• prebuild – PR landed
• prebuild-install – Documentation does not refer to N-API.
• node-gyp-build – Documentation does not refer to N-API.
• prebuildify – PR landed
• prebuildify-ci – Documentation does not refer to N-API.

Since I've contributed to most of the projects that need documentation updates, I will go ahead and create the necessary PRs.

[NickNaso]

Should we change the blog posts we wrote for the Node.js Collections?

[mhdawson]

@NickNaso I think we are probably ok leaving those as is.

[jschlight]

One last thing I see that should be fixed is the GitHub About box for https://github.com/nodejs/node-addon-api

[mhdawson]

@jschlight - DONE

[mhdawson]

Looks like we are done based on update from @jschlight in last Node-API team meeting, closing.