The SDS 1.0 specification lacks adherence to some major REST principles and constraints

[mkaplun]

The SDS 1.0 specification lacks adherence to some major REST principles and constraints.
Here are some specific areas (we will refer to them as Sub-issues) that need to be improved to achieve better compliance with REST in version 2.0:

Sub-issues

1) Resource Structure:
The resource structure should be more consistent and intuitive for better usability and consistency. For example, updating the path for service descriptions to something more intuitive, like /services/{service-id}/service-description.

2) HTTP Status Codes:
The specification mentions HTTP status codes but could provide a more comprehensive list of status codes and their meanings.

3) HATEOAS:
The SDS 1.0 does not incorporate HATEOAS. HATEOAS is a key constraint of RESTful APIs, and it's currently missing in the SDS.

4) Caching:
The specification mentions that operations 'MAY be cacheable,' but it should provide more detailed recommendations for caching strategies.

5) Security:
While the specification mentions the use of authentication mechanisms compatible with HTTP, more comprehensive details on security best practices, including authorization, need to be provided, including recommendations for securing sensitive resources or operations.

6) Versioning:
The specification lacks guidelines for versioning resources to support backward compatibility as the API evolves over time.

Proposed Approach

A separate Issue in the GitHub's repository SDS 2.0 should be created for each sub-issue identified on this list.
In order to facilitate collaborative development, I propose the following approach:

1) Sub-Issue Selection: Developers are encouraged to select one or more of the sub-issues mentioned. By selecting a sub-issue, developers take ownership of working on that specific area.

2) Active Contribution: Once a developer or a group of developers chooses a sub-issue, they become responsible for providing valuable input and solutions to address the identified problem. This involves researching, proposing changes, and actively participating in discussions related to that sub-issue.

3)Solution Proposition: Developers are expected to offer solutions to the sub-issues they've selected. These solutions should align with best practices and REST principles. They might involve proposing modifications to the specification text, introducing new guidelines, or recommending specific implementations.

4) Collective Effort: While individual developers can work on specific sub-issues, this is a collective effort. Collaboration among developers is encouraged to ensure that the solutions provided are consistent and cohesive across the entire specification.

5)Alignment with REST Principles: The primary objective is to bring the SDS 2.0 specification in line with the principles and constraints of REST. Developers should keep this overarching goal in mind when working on their chosen sub-issues.

6) Input for SDS 2.0: The input, solutions, and recommendations provided by developers will contribute to the development of the new version of the SDS specification (2.0). This means that the refined and improved specification will reflect the collective expertise and efforts of the development team.