A colleague of mine approached me with the question about choosing a correct approach for API interface for data filtering. Whether it should be graphql, OData, rest, or just using rpc endpoints with parameters. Further in the article I'm giving hints to choose one.
There is industry practice to use RESTful services for public API and RPC for non-public. Both addressing different concerns. RESTful provides uniform interface for API client and rely on mechanism which already in use in the internet (browser and web server caching, HTTP verbs, etc.) this is helpful when you developing API for UNKNOWN clients from INTERNET. RPC is much more flexible regards to development, but assumes that client knows details of API implementation.
If you're using RPC there is a risk of flooding your API with endpoints for different queries. GraphQL and OData addressing this by exposing querying mechanism to clients. The downfall of this is increased time of development of this mechanism which is not always worth it if you have few endpoints. To keep the balance between flexible querying mechanism and development efforts I would choose the following:
- lean requirements for my API in the beginning using RPC-style
- incorporate schema-driven binding for DTO
- incorporate tolerate reader pattern which enables your code work correctly when DTO is changed
- this will help to decrease code maintenance when changes are not significant
- keep some level of flexibility of your endpoints taking into account business context
To illustrate the last point I'd like to give an example. Imagine you're developing FE which needs data from BE about all events and by person. Before creating an endpoint take a look in which business context it is going to be used. It maybe that all events you need on specific page, and data by person is required on people audit page. In such a case I would create two different endpoints instead of one and follow specific naming convention.
I would NOT DO:
- api\events
- api\events?byUserId=
I would DO:
- api\events – belongs to specific business case of events analysis
- api\auditUserEvents?id= – belongs to specific business case of user analysis
Wrapping Up
As you might have noticed I would recommend to use RPC interface of your API service if it is not exposed to the entire internet. If consumers of the API are well informed about the interface and can directly communicate with development team RPC approach will give boost in development.
If you're developing API service which is supposed to be visible to the entire internet there is more sense to adhere RESTfull approach. It will give more clarity for consumers of your API.
GraphQL, OData and custom approaches based on using dispatcher methods may live together with the above architectural styles. Trade-off should be found between the time needed to implement it and speed of features delivery.
