November 2022 Summaries

Creating an API is fundamental, but how easy it is to integrate into a developer's application stack determines its success in a crowded market. The API consumption journey consists of three phases: discover, explore, and integrate. Poorly designed APIs can lead to unnecessary plumbing, refactoring, and manual effort during integration. In contrast, high-quality SDKs provide code that is accessible, approachable, maintainable, robust, and reliable, making it easier for developers to integrate the API into their application stack. By focusing on these qualities, API providers can deliver a world-class developer experience, improving the overall user experience.

The OpenAPI specification is a widely used format for representing RESTful APIs, offering various tooling support to developers. To write an effective OpenAPI specification, it's essential to follow best practices to ensure compatibility with tools and services. Key considerations include specifying the `servers` property in the root object, limiting titles, names, and summaries to 50 characters, avoiding inline schemas definitions, providing non-empty examples, ensuring valid examples conforming to schemas, defining at least one security scheme, using a unique operation ID, returning a 2XX response for GET operations, adding operation level tags, specifying parameters in order, adding descriptions to API components, including contact information, and reusing components to maintain scalability. By adhering to these guidelines, developers can generate better client libraries (SDKs) and developer portals for their APIs using tools like APIMatic's Code Generator and Portal Generator.

APIMatic's CodeGen OpenShift Operator autogenerates language-idiomatic and production-ready SDKs and API Portal in Red Hat OpenShift clusters, speeding up API onboarding and reducing development overhead. APIMatic has achieved Red Hat OpenShift Operator Certification for its SDK Generation Platform and is now a Red Hat Certified Technology Partner. The platform offers a code generation solution that instantly generates SDKs in multiple programming languages, including .NET, Java, Ruby, PHP, TypeScript, and Python, using an API specification in almost any format, along with a comprehensive API Portal that enables easier API integration and quicker developer onboarding. This platform is part of the Red Hat ecosystem and allows OpenShift users to run the APIMatic CodeGen application in their clusters and automate SDK generation directly into CI/CD pipelines via Tekton and GitHub Actions.

API providers aim to provide SDKs that translate their API specification into client code, but these SDKs are not enough to guarantee good developer experience. A critical analysis of an API's request sample code revealed red flags such as bad HTTP practice, security vulnerabilities, and hardcoded JSON. In contrast, a well-designed SDK provides layers of support for developers, including the API Consumer DX layer with features like failed call retries, configurable logging, and optimized error messages. The API Provider DX Layer offers features tailored for providers, while the language-idiomatic layer provides multi-language support to cater to developers' preferences. A great SDK is one that goes beyond mere translation of the API specification, handling repetition in a library and catering to both providers' and consumers' needs in their preferred language.

APIMatic enhances the functionality of Anypoint Exchange by enabling API providers to generate language-idiomatic SDKs for faster integration, supporting multiple programming languages. To use APIMatic, developers need to publish their assets on Anypoint Exchange and then import them into APIMatic, where they can generate SDKs with customizable settings. The generated SDKs can be used in various ways, including downloading them as a zip file, deploying them on GitHub, or publishing them as packages to language-specific platforms. This process enables developers to create production-ready SDKs that can be utilized on any platform, thereby supporting the adoption of APIs and providing a seamless developer experience.