Principles behind obtuso

This section is dedicated to those who want to understand the core principles behind obtuso. It explains what problem we are solving and why we solve it the way we do. Problem Integrating APIs to build meaningful applications results in a lot of repetitive work. Integrators have to build custom middlewares to deal with different formats and protocols. Lots of proprietary code gets written to integrate 3rd party APIs into an existing IT infrastructure.

Companies have heterogeneous systems of various APIs, more or less documented, hard to re-use and share across projects. Inconsistencies in the domain model and API design are the norm. Implementing Authentication and Authorization is hard. All this leads to unhappy developers, lots of wasted resources and slow projects.

Assumptions

  • Hypermedia APIs are amazing but hard to implement and use.
  • Specifications like OpenAPI leverage HTTP very well
  • OpenAPI brings lots of advantages thanks to the schema but also breaks with Hypermedia principles
  • OpenAPI leverages HTTP very well, making efficient use of the existing infrastructure of the web
  • developers find OpenAPI based APIs hard to optimize for modern use cases like mobile apps and single page applications
  • GraphQL's developer experience trumps over RESTful-ish (JSON over HTTP) APIs
  • GraphQL's community is vibrant, adoption is growing rapidly
  • GraphQL breaks with basic principles of the web, making it hard to leverage existing infrastructure
  • GraphQL comes with a lot of complexity when it comes to security and scalability
  • Solution#
  • obtuso introduces a hybrid model between GraphQL and RESTful APIs.

With obtuso, developers can enjoy the user experience of GraphQL, combined with the scalability and performance of RESTful APIs. obtuso allows developers to onboard all their APIs into the system. obtuso will handle any upstream protocol and translates it to GraphQL. However, in production, all GraphQL operations will be turned into on-demand REST APIs, reducing the attack surface and enabling browsers and intermediaries to cache results. All this happens almost transparently thanks to tools like smart code geneneration to hide the complexity from developers.

Benefits

Instead of writing custom integration code, developers just add the required APIs to a project, write a bunch of GraphQL operations and get a ready to use tailor made sdk in their language of choice, integration done. A lot less custom middleware is required, as obtuso already translates between protocols and lets you join different data sources. No more proprietary code needs to be written to integrate 3rd party APIs. Add their schema to your obtuso application, write a GraphQL Query, generate a client, done. Clean up you heterogeneous system of APIs through the use of obtuso's API registry.

Principles

  • Developers should not think about protocols anymore
  • An API is just another function call
  • Developers should never manually integrate APIs again
  • API clients must always be generated
  • Smart API clients like GraphQL clients with a custom cache implementation are a thing of the past
  • Integrating 3rd party APIs should take no longer than one minute
  • Developers should be able to easily find the APIs they need
  • Developers should not have to deal with AuthN/Z anymore
  • API clients should never send GraphQL over the wire
  • There should not be public facing GraphQL APIs in production
  • You should never have to touch a user interface to configure and integrate APIs
  • All configuration must be done in code, leveraging git for version control and distribution
  • APIs should have just one version of the schema and never break clients
  • APIs must leverage HTTP to its full extend to make caching easy
  • We should always strive to improve the developer experience
  • Every possible repetitive step must be automated