faa-swim / sds20 Goto Github PK

Add the capability to cache SDS responses.
Caching infrequently updated but often voluminous responses by SDS will considerably reduce bandwidth, latency, and load on servers and hide network failures.
A registry associated with an SDS instance may generate and store a "fresh" version of the response each time its content is updated.
Therefore, consistently with REST recommendations, GET requests should/can be cached by default - unless a client asks otherwise.
The handling of a POST request should be evaluated in conjunction with Issue faa-swim/sds20#4.

The resource structure should be more consistent and intuitive. The paths for SDS's resources can be improved for better clarity.

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

Augment or replace the existing request sequence solution with an approach that would allow a requester to simultaneously send requests to all known SDS. Using a requesting instance to combine multiple responses should improve the overall response time for users. For example, in response to a client query request, a discovery service X could forward requests to two other discovery Y and Z and return combined results from all three services (X, Y, Z) to the user.

Support federated authentication mechanisms so that a user registered with one SDS instance can use his credentials to access another SDS instance. For example, an FAA SWIM user should be able to use his NSRR credentials to access KAC SMXS.

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.

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.

The specification mentions HTTP status codes but could provide a more comprehensive list of status codes and their meanings.

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

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

Add the capability to include a Filter expression in an SDS request. This new feature should allow a requesting agent to create a query using criteria currently unavailable through the API's path or query parameters. For example, the query might include a statement to select all services whose "provider" (a schema element) has the value "http://faa.gov/".