The Problem with RESTful APIs

Practical RESTful APIs

• Design APIs around business entities
  • Customers, Orders, Products, etc.
• Uses many concepts of HTTP
  • URL for addressing and joining, query parameters, headers for authentication, methods for operations, etc.
• Schema and documentation using Open API Specification

Problem: Overfetching, Underfetching

• Overfetching
  • https://api.acme.com/customers/ALFKI returns an entire customer
  • What if the client only needs specific fields?
• Underfetching
  • https://api.acme.com/orders returns order headers
  • What if the client needs order details for all orders (N+1 problem)
• Logic on the client
  • https://api.acme.com/customers returns customers ordered by ID
  • What if the client needs data ordered by customer name?

Solutions

• Add more endpoints
  • https://api.acme.com/customers/orderedByName
  • 👍 simple to implement for only a few options
  • 👎 confusing for larger APIs, a lot of work, inflexible
• Use query parameters
  • https://api.acme.com/customers?orderBy=name
  • 👍 flexible, arbitrarily powerful
  • 👎 not standardized

OData

What is OData?

• https://odata.org
  • Relatively old OASIS standard
  • Latest version is 4.01 (2020)
  • Mainly driven by Microsoft and SAP, widely used in their products
    (e.g. SharePoint, Graph API, Power BI, etc.)
• Concepts
  • Based on RESTful API concepts
  • Standardize powerful query capabilities using URL and query params
  • Standardized data manipulation operations
  • Common Schema Definition Language (CSDL)
• Tutorials
  • https://www.odata.org/getting-started/basic-tutorial/
  • https://www.odata.org/getting-started/advanced-tutorial/

Pros/Cons

• Solves over/underfetching problem
  • Gives client a lot of flexibility
• Standardized
  • OASIS standard
  • Widely used in Microsoft products (clients, services)
  • Covered in Microsoft's own API Guidelines 🔗
  • No so widely used outside the MS ecosystem
• Good integration with .NET
  • Largely delivered by Microsoft
• Well-suited for use with (relational) databases
  • OData queries can be relatively easy translated
    into DB queries (e.g. SQL)
• Not the newest and freshest protocol

.NET and OData

• Good integration in ASP.NET Core
  • https://learn.microsoft.com/en-us/odata/
  • https://github.com/OData/odata.net
  • https://github.com/OData/AspNetCoreOData
  • 👍 Used by Microsoft themselves 🔗
  • 👎 In the past, not always 🥬
• Good integration with Entity Framework Core
  • 👍 Relatively easy to put OData service over EFCore model
  • 👎 EFCore data model = OData data model
• Implementation of custom OData providers is possible
  • 👍 Flexibility
  • 👎 A lot of (interesting) work (we did that before)

GraphQL

What is GraphQL?

• https://graphql.org/
• Query and data manipulation language for graph-like data structures
  • Like OData, not bound to a specific DB
  • Unlike OData, not so much designed around relational DBs
• Unlike OData, not a RESTful API
  • Single endpoint, just POST
• Data described using GraphQL's type system (JSON-like)
  • https://graphql.org/learn/schema/
• Queries and mutations using GraphQL's query language (JSON-like)
  • https://graphql.org/learn/queries/

What is GraphQL?

• Tutorials
  • https://www.tutorialspoint.com/graphql/graphql_introduction.htm
  • https://www.apollographql.com/blog/graphql/examples/what-is-a-graphql-query-graphql-query-using-apollo-explorer/

Pros/Cons

• Solves/moves over/underfetching problem
  • Gives client a lot of flexibility
• Popular
  • Widely used in modern distributed systems 🔗
  • Support in many popular tools (e.g. Postman 🔗)
• No .NET support provided by Microsoft, but from 3rd parties
  • Server- and client-side libraries for many languages
  • https://graphql.org/code/
• Not so well-suited for use with (relational) databases
  • N+1 problem on the server
  • Complexity through Data Loaders

.NET and GraphQL

• Two popular GraphQL server implementations
  • https://chillicream.com/docs/hotchocolate
  • https://graphql-dotnet.github.io/
  • 👍 Exists for quite a while, active
  • 👎 No supported directly by Microsoft
• Decent integration with Entity Framework Core
  • 👍 Integration with EFCore 🔗, support for IQueryable 🔗
  • 👎 GraphQL not designed primarily with DBs in mind
• Implementation of custom GraphQL providers is possible
  • 👍 Flexibility
  • 👎 A lot of work to do it right

SignalR

What is SignalR?

• https://github.com/dotnet/aspnetcore/tree/main/src/SignalR
  • ​https://learn.microsoft.com/en-us/aspnet/core/signalr/introduction
• RPC protocol
  • Call methods on client from server and vice versa
  • Uses WebSockets, fallbacks available
• Cross-platform
  • Server-side practically always .NET
  • Various clients available 🔗
• Typically not a replacement of API, but an addition
  • Enhance request/reply API with "real-time" features
  • Duplex communication between server and client
• No schema language

SignalR without SignalR 😕

• Azure SignalR Service
  • https://learn.microsoft.com/en-us/azure/azure-signalr/signalr-overview
• SignalR to the frontend, REST in the backend
  • Completely cross-platform
  • No need to worry about scaling
  • Cost-efficient

.NET and SignalR

• Server: Very good integration of SignalR in ASP.NET Core
  • https://learn.microsoft.com/en-us/aspnet/core/signalr/introduction
  • Provided directly by Microsoft
• Client: Libraries available for multiple platforms
  • Including .NET, Java, JavaScript/TypeScript
• Gain independence from protocol using Azure SignalR

Other Options

Invent Your Own QL

• Invent your own query language
  • Based on existing grammar (e.g. JSON, YAML)
  • Custom grammar (DSL)
• Frequently done in COTS SaaS applications, examples:
  • Zoho COQL 🔗
  • TCQL 🔗
  • Sugar CRM API 🔗
• Pros/Cons
  • 👍 Flexibility, can be tailored to specific needs
  • 👎 Complexity, a lot of (interesting) work (done it before)

gRPC

• https://grpc.io/
  • https://learn.microsoft.com/en-us/aspnet/core/grpc/
• Support for browser clients with gRPC-Web
  • https://learn.microsoft.com/en-us/aspnet/core/grpc/grpcweb
  • https://www.envoyproxy.io/
• Very good integration in ASP.NET Core
  • Provided directly from Microsoft
• Pros/Cons
  • 👍 Simple protocol, fast
  • 👎 No query language, additional layer on top needed