REST API and it’s management


For many front-end, back-end and integration developers, the REST API management is hazy.

What does it include, what does it mean regarding the design of APIs? Our APIs are already visible over the internet, do we need this now? A developer would rather jump right away into GraphQL or just offer simple APIs generated from database?

Front-end developers working mainly with GraphQL are having to make the same design decisions traditionally applied to REST APIs and made by back-end developers. And if there is a REST API back-end for the GraphQL server to use, then you either patch bad REST things up in GraphQL or you risk doing all the design failures (again) in GraphQL which you might have had or avoided in REST.

To clear this, here’s a summary of the thought process a REST API developer goes through:

  • Use OpenAPI (previously Swagger) -definitions for your API. OpenAPI 3.0 starts to be quite well supported already in tooling.
  • Use API management-process and tooling
  • Use OpenID Connect (not API keys, not just OAuth). Use also token-based claims for access management. This is important for personal or otherwise sensitive data, but also if your API has multiple users like partners or customers who should only access their own data.
  • Design according to customer need, efficiency and best practices, don’t go too general purpose but don’t design just for one application. Consider making your API endpoints query friendly and limiting the number of returned attributes.
  • Do not change your APIs version number (if any) unless there is a major change which is not backward compatible. Choose a versioning strategy that matches your API management tooling.
  • Remember that if you expose an endpoint to open web without any authentication you risk others starting to use it even if it’s not an actual security risk. Even for public data use normal security measures you would for a website but also authentication.
  • Use HTTP status codes wisely, remember that there is more than 200 ok:
    • 4xx for “it’s your fault” as a consumer (don’t hide “it’s my fault” in here, it’s misleading)
    • 5xx for “it’s my fault” as a provider

Metrics and monitoring should be in place for endpoints, for debugging, auditing and possibly even monetizing the usage.

API management minimal role

Typical minimum features include

  • API Proxy
  • Gateway between different network environments
  • Authentication of API calls
  • Rate Limiting per API
  • Throttling per API
  • API subscription management (subject to Website exploits)
  • Analytics of API calls
  • Versioning APIs and transitioning consumers, managing API life-cycle
  • Documentation (executable/testable/partly automatically generated), code snippet generation

Some additional features you might need depending on the developer experience you want to offer:

  • Providing specification files to consumers
  • Subscription plans & rate limits, naming, support
  • Monetizing APIs
  • Community management, communications with API consumers and non-developers needing information on the APIs
  • API Presentation Portal

After this brief thought process, we’re now able to talk about GraphQL and moving forward with a Mobile First development approach.