Subramanian Krishnan

August 20, 2022

The untold story of our API journey

Background

Sometime in the mid of 2018 we at Citrix embarked on a journey to get better at how we do APIs. We have come a long way from where we started and there is a lot more to be done. It has been an adventurous and challenging journey and I believe it’s an inspiring story worth telling others. I’m sure there are many within the company who don’t know about it. This post is my attempt to share the story and by way of doing that celebrate all the efforts that have gone in to build the API platform and all the people who contributed to make it what it is today.

Note: In order to keep it suitable for public consumption I will keep it at a high-level so as to not bore readers with details. Likewise this post will highlight the good/positive stuff. The dirty linen is washed in private.

With that disclaimer, we are all set for the story. Here we go.

// Once upon a time in 2018

There were no company level API style/design guides. A previous attempt to create one had resulted in a bunch of documents with views for different aspects of API design. It was neither comprehensive, nor agreed upon. It was not published either. We happened to find it while digging some old archives.

The API documentation was also not in a great shape. Each product/service documented their APIs (if at all) in their own way and published it at a place of their choice. For ex. some chose to make it a part of their product documentation, some allowed downloading it from the help section of their instance/tenant, some had a dedicated website for their API documentation and few other variations.

Even the format/style of documentation varied. Some had a pdf for the APIs, some had a zip file with html files describing the APIs, some had curl examples embedded in the API section of the product documentation, and so on.

Most services were not using an API gateway thought they had some WAF mechanism in place to prevent against common attacks.

Fast forward to 2022 >>>

In the last few years with good amount of work done by a bunch of committed folks across functions, there is tangible and vast improvement in all the above mentioned areas.

API Guidelines

  • We have published guidelines for REST API design for use across the company. It was discussed, debated and documented in a collaborative way by representative architects from each service/product. All architects signed off on the guidelines before it got accepted and published for company wide use.

  • We developed an in-house tool to check OpenAPI specs for compliance with guidelines and give feedback. The validation capability is itself exposed as a service with its own API for CICD automation.

  • There is a dedicated slack channel and virtual team of experts one can reach out for guidance and clarifications.

Note: One of the most satisfying activity for me is when I get pinged by someone who is working on designing a new API and seeks guidance/feedback/review for it. And I’m not the only one. There are many other experts/champions who are willing to help others make good APIs. Likewise many times people ping to understand the rationale behind a guideline and what alternatives were considered and I try my best to give them the historical context.

API Documentation Portal

  • We now have a unified portal for developer documentation. It’s a documentation umbrella which leads to API docs, SDKs, forums, legacy documents where new ones don’t exist, developer event info etc.

  • Many (but not all) services now have OpenAPI documentation which can be downloaded from the portal. It also has the Getting started, Try it now, Sample snippets in select programming languages, FAQs and other companion documentation for the APIs.

  • The portal is self-service and API developers can get their documentation on-boarded to the portal by checking in a bunch of markdown files and the OpenAPI spec. There are custom linters integrated into the pipeline which check the submitted files for format and syntactic correctness.

  • We collect analytics for how external audience is engaging with the portal and have reasonable visibility into and awareness of how the portal is being used.

Note: For those who are used to seeing advanced/mature portals, this might invoke a - “What’s the big deal?” reaction. But those who knew our state of affairs before 2018, understand that it is a big deal.

API Gateway

  • We have API gateways deployed (in multiple geos) with production traffic routed through them. Many services now route their APIs through the API gateway.

  • When we started the initiative, we used to go around requesting services to on-board their APIs. Now the tides have turned. Service owners chase the platform team now.

  • The gateway infrastructure is self-service and anyone can deploy API proxies to the dev instances by simply checking in some config files. Progression to higher environments needs further review/approvals due to compliance, security, capacity and SLA reasons.

  • The APIs on the gateway automatically get additional security through an ingress layer in front of it which implements WAF rules. High availability of the gateway is achieved through multi-region active-active deployments.

  • Traffic passing through the gateway allows us to collect data/metrics for subsequent analytics and reporting. We have dedicated dashboards for PMs and dev/ops to show them API related data/insights relevant to them.

  • In some cases we were able to extract common business logic and make it a policy which can be applied at the API gateway layer. This spares lot of dev and testing effort for service implementation which now only have to configure the API proxy with the custom policy instead of implementing it from scratch.

  • Some services have used API gateway policies to achieve compliance with API guidelines (when feasible) without having to change the existing service implementation.

Closing thoughts

Building an API platform is a journey and not a destination. As we look back, there are many accomplishments to feel good about and at the same time there is lot more that needs to be done. For those out there who are way ahead in the journey - “Thank you! for inspiring us and showing a way.” For those who are behind or have not started, few cents of advice:

  • Start moving and take it one step at a time.

  • Celebrate and acknowledge every bit of progress you make.

  • Measure your progress by the value addition you are doing in terms of new capabilities, adoption and feedback from users. The value of technology platforms can’t be always quantified in revenue and dollars. That doesn’t mean they lack value.

  • Remember a platform is as much a mind game (maybe more) as it’s a technology game. You will come across resistance, rigidity, discouragement, disappointment etc. The key is to not give up and keep moving. Look out for allies who are willing to support you and walk alongside you.

  • Make use of every opportunity to talk about the capabilities offered by the platform and the benefits of using it. Don’t lie but don’t be shy either in talking about what works and what is good.

  • Dream big and bold even if the funding and support is lacking. It will keep you motivated, positive and on the learning path. Life will eventually give you a chance to make it a reality.

← All stories