Standardize API Naming Conventions

[cds-amal]

Summary

This issue addresses the ongoing taxonomy concerns within the DIN API suite, focusing on the proposal to replace the term "Endpoint" with "Method" for consistency and clarity. Since this is part of a larger set of terminology changes, we should track and manage these updates holistically to ensure alignment across the project.

Proposal

• Replace the term "Endpoint" with "Method" throughout the API documentation, codebase, and interfaces.
• Review other related terms to maintain consistent naming conventions that align with the project’s goals and standard practices.

Rationale

The terms "Method" and "Endpoint" have well-established meanings in the INFURA and broader infrastructure domain. To align with industry standards, we should adhere to these conventions.

List of terms under review:

• [ ] Endpoint -> Method
• [ ] Service -> ???
• [ ] EndpointCollection -> MethodCollection | ChainMethods

Action Items

• Conduct a comprehensive review of the API to identify where terms like "Endpoint," "Collection," "EndpointCollection," and "Service" are used.
• Gather team feedback on additional terminology that may need updates for consistency.
• Update the API documentation, codebase, and any relevant materials to reflect the changes.

Next Steps

1. Review, implement the changes, and close the issue once all updates have been merged.

Additional Considerations

• Should we establish a glossary or style guide to ensure consistency moving forward?

Reference

1. https://github.com/DIN-center/din-sc/pull/37#discussion_r1744201505

[clemenswancs]

I can just offer that the standard REST API nomenclature is:

• Endpoint: Refers to a specific URL pattern that the API exposes, allowing clients to interact with a resource. An endpoint usually represents an address where resources are accessed via HTTP methods (e.g., GET, POST).
• Method: Represents the HTTP method used to interact with an API endpoint, such as GET, POST, PUT, DELETE, PATCH, etc. In some contexts, "Method" can also refer to a function or operation that can be performed within an API.
• Resource: Denotes an entity or a collection of entities that the API manages. For example, in a RESTful API, resources could be users, orders, or products, typically represented in JSON or XML format.
• Request: The data sent by the client to the server when invoking an API method, including the HTTP method, headers, body, and query parameters.
• Response: The data returned by the server to the client after processing an API request, often including status codes, headers, and the body content (e.g., JSON or XML).
• Collection: In RESTful APIs, a collection typically refers to a group of resources (e.g., /users might return a collection of user resources). It's often associated with endpoints that return lists of resources.
• Service: Generally refers to a higher-level abstraction that encompasses one or more APIs or endpoints. A service might represent a specific set of functionalities offered by an API, such as user management, data processing, or authentication.
• Operation: Sometimes used interchangeably with "Method," especially in SOAP or RPC-style APIs. It refers to a specific action that can be performed on a resource, like fetching, creating, updating, or deleting.
• Route: Another term for an endpoint, often used in web frameworks to describe the path and method combination that maps to a specific controller or handler in the server code.
• Controller/Handler: In some architectures, this refers to the server-side code that processes the API requests. Each controller or handler typically corresponds to a specific endpoint or set of endpoints.
• Middleware: Refers to functions that are executed before the final handler/controller processes the request. Middleware is often used for tasks like authentication, logging, or request validation.
• Payload: The body of the request or response, typically containing the data being sent to or returned from the API.

[natefikru]

also potentially want to look at the following din_api -> din_registry endpointMeta -> methodMetaData

also i would like to discuss potential renaming endpointCollectionRegistry to something that more closely resembles the representation of the network/services that it represents. for example like serviceRegistry or networkRegistry. Reason being the collection of methods that these structs represent really are just describing the capabilities of a service/network within the Din Protocol. My opinion is that method management doesn't need to take up so much space when it comes to the naming and organization of the data definitions.

[natefikru]

updates from the meeting:

rename dinApi to dinRegistry change references of endpointCollection to network collectionService -> networkService endpointMeta -> networkMeta

potentially rename endpointCollectionRegistry(networkRegistry) -> networkHashTable or networkDict