Add notifications API specs

[spapadop]

Description

Currently notifications API specs are missing, along with a number of others, as described at #168.
This PR will cover the gap for the notifications API.
Note: I know the PR is not complete as it does not cover all notifications API calls yet, just wanted to get an initial feedback to ensure I'm on the right path. And couple of questions:

1. Should the "model/notifications" folder that I am adding rather be placed under model/_plugins/notifications so that future missing API specs end up within model/_plugins too?

2. Shall I also update the OpenSearch.openapi.json accordingly, or is there an automation to take care of that?

Issues Resolved

• part of [FEATURE] Add missing API specs #168

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[dblock]

@nhtruong take a look?

[nhtruong]

Thanks @spapadop. To answer your questions:

1. putting it in model/notifications is exactly what we want IF this plugin has become a core feature of Opensearch. That's what we did with the security plugin.
2. The OpenAPI file will be updated automatically by a follow-up PR.

One thing to note about the xOperationGroup. It serves 2 purposes:

• Grouping operations with identical functionality. For example the search API action is comprised of 4 operations. Notice how they all have identical @documentation?
• It dictates the namespace and the API method name on the clients. For example, indices.create will result in client.indices.create() in the clients.

For the vast majority of API actions, like those in the notifications plugin, there's only 1 Operation per action. The 2 operations in your operations.smithy file should belong to 2 different OperationGroups (say notifications.get_configs and notification.create_config) and should be put in separate locations (model/notifications/get_configs/ and model/notifications/create_config)

The reference should also use anchor to pinpoint the location of the API doc on the page:
That is, use https://opensearch.org/docs/latest/observing-your-data/notifications/api/#list-all-notification-configurations
instead of https://opensearch.org/docs/latest/observing-your-data/notifications/api/

I'll update the DEVELOPER_GUIDE to make it more clear.

[spapadop]

Hi @nhtruong, many thanks for all the input and sorry for the late answer (long break for me), it's more clear now! I'll continue work on this one and come back to you asap.

I see Notifications is documented under "Observability", so it rather feels more like it should go under _plugins folder, which will later include the majority of things mentioned here. Let me know if you have any objections, else I'll go ahead with that structure.

[nhtruong]

Is notifications gonna be a part of the core client. If so, it should be in the notifications namespace so that a call to one of its endpoint from the client will look like this client.notifications.create_channel.

@dblock what do we do with plugins?

[spapadop]

I believe it's not gonna be part of the core client. Notifications API is not worked yet in the python client, but seeing that there is a plugins folder there, already containing alerting and index_management, I'd guess notifications also belongs there. So the endpoint from the client will look like this client.plugins.notifications.create_channel.

But I'll let @dblock confirm.

[Xtansia]

@spapadop Thanks for making those changes, just a couple minor things left to fix and please also rebase your branch onto the latest main so that the API Coverage workflow can pass.

[github-actions]

API specs implemented for 241/649 (37%) APIs.

[spapadop]

@Xtansia many thanks for the thorough review! I applied your suggestions and synced my fork.
Back to you