Proposed New Feature: Add Filtering Capabilities to SDS

[wznira]

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/".

[swang-nira]

Dear Colleagues,

I have a proposal solution for this feature and would like to discuss here. As we know, GraphQL gains more and more popular in industry nowadays. Some people even say it’s a better REST API. There are multiple features provided by GraphQL which are not available in REST API. Below is some background information about GraphQL and comparison between GraphQL vs. REST API:

One of the most common problems with REST is that of overfetching and underfetching. This happens because the only way for a client to download data is by hitting endpoints that return fixed data structures. It is very difficult to design the API in a way that is able to provide clients with their exact data needs. The issues of overfetching and underfetching resources is that the server side imposes specific data view point of the client, forcing clients to perform multiple calls to the server to get the data following the structure needed by client or getting too many information for displaying specific views, especially in mobile environment. Another issue with REST APIs is that there is no standard way to describe the schema of the data model to the client that allows the discovery of APIs without writing custom code.

To address these gaps, Facebook published in 2015 the GraphQL specification, which provides a query API for APIs. GraphQL not only provides a single endpoint to perform CRUD operations but also a publish/subscription mechanism for asynchronous communication. In addition, GraphQL provides a schema language (GraphQL Schema) that enables clients to discover the data model and operations allowed on the data model in a consistent way and then perform validation on client and server side.

GraphQL query language enables clients to define the exact structure of the response (including aliasing of field names) giving back control to clients to define what data needs to be returned. This solves the issue of overfetching and underfetching in a REST API. This significantly improves performance of the applications by minimizing the number of requests and payload size exchanged with the service. A large number of vendors have adopted the GraphQL standard (GitHub, AWS, Facebook, Twitter) and libraries exists for mostly all programming languages making it easy to integrate with any clients.

From above, seems like GraphQL could be a solution for the filtering capabilities to SDS. Let's discuss it and please add your comments/thoughts or questions here.

I will paste a comparison between GraphQL vs. REST API below.

Thanks, Sam

[swang-nira]