March 2018 Summaries

The Developer Experience (DX) Portal is a one-stop solution for API needs, consolidating services such as SDKs, documentation, reactive code samples, test cases, CI/CD integrations, and package publishing on a single platform. The portal's design was iterative, with multiple iterations of wireframes, mock-ups, and final designs, incorporating feedback from the development team to refine its functionality and usability. The design process involved testing mock-ups, addressing issues such as navigation bars, console placement, and button layout, resulting in a cleaner and more functional UI that effectively delivers its functionality to end-users.

APIMatic has been instrumental in helping Idfy, a Norwegian API provider, expand its services to multiple developer platforms and improve its API adoption and developer experience without substantial effort from their end. By utilizing APIMatic's automated SDK generation capabilities, Idfy can now deliver on platforms that they wouldn't have been able to support themselves, focusing instead on creating APIs for various applications. This has enabled the company to streamline its development process, reduce time-to-market, and improve its developer experience, ultimately providing a competitive advantage in the market. With APIMatic's support, Idfy can now deploy SDKs in 8 languages in the same time it took to deploy them in one language before, and has seen significant cost savings and improvements in its developer experience. The company plans to continue utilizing APIMatic to deliver its APIs to more customers and create new products that require API creation for customers with limited knowledge or experience. Overall, APIMatic has enabled Idfy to become a complete API company without requiring language-specific knowledge on all platforms in-house.

The company has released a major update to its HTTP documentation for all customers, featuring new Curl examples and improved authentication documentation. The updated docs now provide detailed information on common authentication types such as HTTP basic, OAuth 2, and custom API keys, along with interactive Curl examples that users can try out in the terminal. These updates aim to improve the developer experience by providing more comprehensive and user-friendly documentation for developers working with the company's API portal.

API developers should design their APIs with a focus on user experience, ensuring that they are intuitive, flexible, and easy to use. This can be achieved by following best practices such as planning and strategizing, designing for clarity and simplicity, writing code that is readable and maintainable, and providing comprehensive documentation and SDKs. Additionally, API developers should prioritize testing, versioning, authentication, limiting, throttling, consumption, documentation, SDKs, responsiveness, and scalability to ensure the success of their API. By following these guidelines, API developers can create APIs that are user-friendly, reliable, and scalable, ultimately driving adoption and success.

The latest iteration of OpenAPI Specification, OAS 3, has been adopted by many developers, but common mistakes are still being made when migrating from OAS 2.0 (Swagger 2.0). Using the old `swagger` property to specify the version is invalid in OAS 3, and instead, the new `openapi` property should be used with semantic versioning. Defining body parameters in the "parameters" section is also incorrect, as they should now be placed under the `requestBody`. Additionally, declaring response headers as a list of Header objects or an array of reference header objects is not allowed according to the specification. Furthermore, referencing undefined OAS 3 components without defining them first can lead to issues with tools that use this format. These mistakes can be avoided by using the correct syntax and adhering to the official specifications.