<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[APIMATIC - Medium]]></title>
        <description><![CDATA[Developer experience platform that generates SDKs and developer documentation for APIs and transforms API description formats. Visit https://apimatic.io/ - Medium]]></description>
        <link>https://medium.com/apimatic?source=rss----f3aa4093ec86---4</link>
        <image>
            <url>https://cdn-images-1.medium.com/proxy/1*TGH72Nnw24QL3iV9IOm4VA.png</url>
            <title>APIMATIC - Medium</title>
            <link>https://medium.com/apimatic?source=rss----f3aa4093ec86---4</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Mon, 16 Nov 2026 00:35:18 GMT</lastBuildDate>
        <atom:link href="https://medium.com/feed/apimatic" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Your OpenAPI Isn’t Ready for SDK and Docs Generation. Yet.]]></title>
            <link>https://medium.com/apimatic/your-openapi-isnt-ready-for-sdk-and-docs-generation-yet-3a82f15412f3?source=rss----f3aa4093ec86---4</link>
            <guid isPermaLink="false">https://medium.com/p/3a82f15412f3</guid>
            <category><![CDATA[genai]]></category>
            <category><![CDATA[open-api]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[developer-portal]]></category>
            <category><![CDATA[sdk]]></category>
            <dc:creator><![CDATA[Faria Rehman]]></dc:creator>
            <pubDate>Mon, 02 Dec 2024 09:02:16 GMT</pubDate>
            <atom:updated>2024-12-02T09:02:16.049Z</atom:updated>
            <content:encoded><![CDATA[<p><em>We’re APIMatic.io. We generate strongly typed SDKs and complete API documentation from OpenAPI definitions. If you want to create an SDK for your REST API, check out how to </em><a href="https://www.apimatic.io/blog/2022/08/how-to-create-sdks-for-your-api-in-less-than-a-minute/"><em>generate one in under a minute</em></a><em>. We support generating SDKs for C#, Java, PHP, TypeScript, Python, Ruby, and Go using the APIMatic Code Generator.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*6_kpIQ7QAuSEdEO1" /></figure><p>OpenAPI is one of the most widely used standards for defining HTTP APIs, but despite its popularity, we at APIMatic often encounter problematic OpenAPI definitions. These issues range from straightforward standard violations (think broken $refs) to problems that negatively affect SDK and documentation generation (think inline schemas, missing examples), ultimately hindering our users from fully benefiting from our Developer Experience solutions.</p><p>In fact, the challenge is significant enough: approximately <strong>95%</strong> of the definitions we receive contain at least one issue. This might seem surprising, considering the number of validators and linters available to help users create valid OpenAPIs. However, merely being valid is often not enough, and the criteria for being valid can vary between tools.</p><h3>Why are most OpenAPIs problematic?</h3><p>In my opinion, the problems stem from the following reasons:</p><h4>Your validator/linter tool choice influences your output</h4><p>Different tools serve different purposes. As an example, validators like Swagger Editor can help you achieve standard compliance to a great deal but they won’t lint and catch issues related to security, documentation and code generation. Then there are linters like Spectral that give you great support for linting but are more lenient when enforcing standard compliance, allowing some issues to slip through.</p><p>For obtaining an optimal OpenAPI definition, you may be better off using a combination of tools — though identifying the right combination isn’t always straightforward.</p><h4>Hard to find a validator/linter focused on code generation</h4><p>You’ll rarely come across validators or linters designed specifically for code generation that come with predefined rulesets, as this is a niche domain. While linters allow you to create custom rules based on your specific needs, the challenge lies in knowing exactly what to check for — something that’s not immediately obvious unless you’re an expert in the field.</p><p>As an example, a common issue we see in this area are inline schemas which are “anonymous”:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/5ec1fc8ca84d0339cc0afdc0e26ef895/href">https://medium.com/media/5ec1fc8ca84d0339cc0afdc0e26ef895/href</a></iframe><p>While such schemas do not violate OpenAPI standards and are not flagged by tools, they can pose problems when code generation tools require unique names for schemas. Without these names, tools often auto-generate them, leading to code that is less user-friendly. A better approach would be to represent the schema with a unique identifier, such as “Product,” as shown below:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/3ae09aef1ddc5192f677d71fd96004a4/href">https://medium.com/media/3ae09aef1ddc5192f677d71fd96004a4/href</a></iframe><h4>Size of the API matters</h4><p>The sheer size of the API and its definition can influence the number of issues found in an API definition document. For instance, if your API has more than 50 endpoints, you’re likely dealing with over 500 schemas, give or take. This could easily result in an API definition encompassing several thousand lines. Ensuring that every parameter and schema has proper descriptions and examples to generate user-friendly documentation easily becomes a substantial task.</p><h4>Auto-generated OpenAPIs can lack metadata</h4><p>OpenAPIs are often auto-generated from annotated code, as is the case with Swashbuckle for .NET. You can easily generate a valid OpenAPI file with only basic annotations. However, a basic OpenAPI file isn’t necessarily complete; for example, it may lack detailed descriptions and examples unless you choose to add that information yourself.</p><h3>Why Should I Care?</h3><p>Your API definition is a critical piece of your whole Developer Experience program. Here are a few reasons why it matters:</p><ul><li><strong>Ease of integration</strong>: The quality of your API definition directly influences the quality of generated artifacts like SDKs and documentation. Well-crafted SDKs and documentation in turn can greatly reduce integration time for your end-users. In today’s era, such API definitions can also help power AI assistants that can further expedite integration tasks and support the development of applications that drive market success.</li><li><strong>Compatibility with tools: </strong>A standards-compliant API definition will work seamlessly with all kinds of API tools, giving you access to a broader ecosystem.</li><li><strong>Increased Usability and API Adoption: </strong>A user-focused API definition with plenty of examples and clear descriptions results in documentation that is much easier for your end-users to understand and work with when integrating with your API.</li><li><strong>Faster time to market</strong>: If you are careful and consistent with your naming conventions, your development process will be less error prone and save valuable time.</li></ul><h3>So, What Should I Do?</h3><p>If you are an API provider looking to auto-generate SDKs or documentation from your API definitions, it is important to first assess <strong>how</strong> good/bad your API definitions currently are, identify <strong>which</strong> areas need most improvement, <strong>plan</strong> accordingly and then take <strong>action</strong> to address the identified issues. Once you’re confident in the quality of your API definitions, it’s time to generate and enjoy the results!</p><p>APIMatic has recently launched two products<a href="https://www.apimatic.io/solution/score-my-openapi"> Score My OpenAPI</a> and <a href="https://www.apimatic.io/solution/fix-my-openapi">Fix My OpenAPI</a> to help streamline your whole API definitions improvement process described above.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*bMRsnBh1eomkqMrG" /></figure><h4>Step 1: Assess Your API Definition with Score My OpenAPI</h4><p>Head over to<a href="https://www.apimatic.io/solution/score-my-openapi"> Score My OpenAPI</a> to quickly receive a <strong>free</strong> audit report for your API definitions, delivered directly to your inbox:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*c5H_FEqn-LBFyHUXPTvq3g.gif" /></figure><p>The report will highlight:</p><ul><li>The <strong>overall score </strong>for your API definition out of 100. Anything below 50 means trouble while anything below 90 can imply some compromise on the quality of output you can get from your API definition. This, along with the total number of issues identified, will give you a better idea of <strong>how</strong> much work your API definition still needs.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*UjqVnHLwB1UVYQoH" /></figure><ul><li>Additional statistics that show the most affected areas, so you can <strong>prioritize </strong>accordingly.</li><li>A <strong>bird’s eye view of all issues</strong>:</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Wcoaq0Ndwmn9aj0I" /></figure><ul><li><strong>Details for each specific issue</strong> including a description, actionable hints and external links to help you fix the problem, along with a list of affected components with precise file and line locations.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*mlx2mHUGSb1U-Acs" /></figure><h4>Step 2: Debug your OpenAPI with Fix My OpenAPI</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hlW0dKtLfYblAiiYfvdMRQ.gif" /></figure><p>After identifying the issues, the next step is to work on eliminating them. If there are too many issues, the task can quickly become overwhelming. Keeping that in mind, we created <a href="https://www.apimatic.io/solution/fix-my-openapi">Fix My OpenAPI</a>, a VS Code extension tool that comes bundled with over 1200+ rules to help you fix everything — from standard compliance issues to those related to code generation and documentation. It will not only allow you to edit and fix your API definitions in a familiar environment but also helps speed up the process with advanced features like auto-fixing.</p><p>The extension includes dedicated views to help you quickly navigate through issues, prioritize them based on your needs, and resolve them using embedded help content, also within the extension.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*eUtd8x4yeRZor5cj" /></figure><p>As you make progress, the extension will update your score in real-time. You can even generate subsequent audit reports to share with stakeholders, if needed.</p><p>You can download the extension from VS Marketplace<a href="https://www.apimatic.io/cs/c/?cta_guid=5460378e-4f3a-43f1-985f-1290632e100e&amp;signature=AAH58kE7RebXbpE-p-RjteIlV5Wt4rvZhQ&amp;pageId=151840351140&amp;placement_guid=a71b0d94-3c82-4f01-8650-1072ee264e52&amp;click=e682a81c-7b47-48b0-a818-ceb8c0c68ca9&amp;hsutk=bc33c90305f89bcc8817ad92b451eca4&amp;canon=https%3A%2F%2Fwww.apimatic.io%2Fopenapi%2Farray-of-objects&amp;utm_referrer=https%3A%2F%2Fapp.hubspot.com%2F&amp;portal_id=2052727&amp;redirect_url=APefjpHQZdYrrK7_iKM13Lb09MxgTPUjvg64bgEfL8QJdPQwwlzdVXdPNaYTMatTW45ytigZ1Q3iMOykoZYzdIC0TLTR6N00A6LSJtJV34L2bFRuuaz_1ETcnhteoowZ8hRApQ16EblMOcVGNLIVnmzG-M45M5La5SpUOmknLyMBWNl3EvXqpJdDAVm_K0I3MoOVXAp-Alp1fxlEUWgpaIYW4Qmdl9Fd-xRDncZjCfvmGLztuvTYuuDJt6Ox2AiKb5X9sCfc6wc-6ztMBuffqStMqeWaeLaO9jRXkEDTF0JgFED4OseZEX7pVqojCMvh2sFxs1xXcJxh&amp;__hstc=245086810.bc33c90305f89bcc8817ad92b451eca4.1692971644687.1725963122358.1725971449561.318&amp;__hssc=245086810.7.1725971449561&amp;__hsfp=2690863775&amp;contentType=standard-page"> here</a>.</p><h4>Step 3. Repeat 1 and 2</h4><p>Continue assessing and optimizing your API definitions until you are satisfied with their score and overall quality. Once you’re confident, you’re ready to move to the next step.</p><h4>Next Steps: Auto-generate a Developer Experience Kit 🎉</h4><p>If you’ve managed to get a good score and gain more confidence on your API definitions quality, congratulations! You are all set for the next step: auto-generation of a complete Developer Experience package with APIMatic. This package includes SDKs in multiple languages, documentation with a try-it-out console, dynamic code samples as well as an<a href="https://docs.apimatic.io/changelog/introducing-api-copilot/"> API Copilot</a> to further streamline your process.</p><p><a href="https://app.apimatic.io/account/register">Sign up for APIMatic</a> today and get started!</p><h3>Conclusion</h3><p>A well defined API definition goes hand in hand with a great developer experience. Optimize your API definitions with APIMatic to auto-generate high quality SDKs and Developer Experience portals with cutting-edge AI technology. This approach will not only reduce your time to market but also increase API adoption rates.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3a82f15412f3" width="1" height="1" alt=""><hr><p><a href="https://medium.com/apimatic/your-openapi-isnt-ready-for-sdk-and-docs-generation-yet-3a82f15412f3">Your OpenAPI Isn’t Ready for SDK and Docs Generation. Yet.</a> was originally published in <a href="https://medium.com/apimatic">APIMATIC</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[APIMatic SDKs in Backstage Developer Portal]]></title>
            <link>https://medium.com/apimatic/apimatic-sdks-in-backstage-developer-portal-7f763af2df47?source=rss----f3aa4093ec86---4</link>
            <guid isPermaLink="false">https://medium.com/p/7f763af2df47</guid>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[sdk]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[backstage]]></category>
            <dc:creator><![CDATA[Sid Maestre]]></dc:creator>
            <pubDate>Thu, 04 Apr 2024 22:59:49 GMT</pubDate>
            <atom:updated>2024-04-04T22:59:35.366Z</atom:updated>
            <content:encoded><![CDATA[<p>By combining APIMatic’s high-quality idiomatic SDKs with the Backstage developer portal, you can create a compelling and differentiated developer experience.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*ErSXdspxs6atE9tD.png" /></figure><h3>What is Backstage?</h3><p><a href="http://backstage.io/">Backstage</a> is an open-source platform developed by Spotify for managing the entire lifecycle of developer infrastructure, including services, APIs, documentation, and more. Backstage streamlines the development process through its centralized and customizable platform, offering a unified dashboard that consolidates information on projects, services, and infrastructure. Acting as a service catalog enhances transparency by allowing teams to document and discover internal services easily. Backstage’s extensible architecture supports a robust plugin ecosystem, enabling teams to tailor the platform to their specific workflows and preferences. The platform promotes collaboration, accelerates onboarding through standardized documentation, and integrates seamlessly with various DevOps tools.</p><h3>Extending Backstage with SDKs</h3><p>As the number of services and API complexity grows, teams using Backstage as their developer portal may look to add SDKs to support developers in multiple languages. SDKs include code libraries, documentation, getting-started guides, and code samples, empowering developers to interact seamlessly with APIs and services.</p><p>APIMatic automates the creation and maintenance of SDKs in various programming languages. In this tutorial, we’ll show you how to take your API developer experience to the next level by using APIMatic to generate SDKs and incorporate them into your Backstage portal.</p><p>APIMatic goes above and beyond to ensure a good developer experience by providing auto-generated SDKs in the programming languages you need and includes SDK documentation with guided walkthroughs, code samples, and getting started guides.</p><p>We can integrate APIMatic SDKs by incorporating them into a dedicated SDKs page within existing documentation or by embedding the SDKs documentation as a newly registered component in the Backstage portal. In the upcoming sections, we will explore both options to see how they can improve the developer experience within the backstage portal.</p><p>Have a look at the final result.</p><h3>Generate SDKs and Documentation with APIMatic</h3><p>In this section, we walk through publishing an API portal for APIMatic SDKs. If you already have a generated portal with APIMatic, skip to <a href="https://www.apimatic.io/blog/2024/01/apimatic-sdks-in-backstage-developer-portal#integrate-apimatic-with-backstage">Integrate APIMatic with Backstage</a> section.</p><p>Start your free trial with access to all SDK generation features.</p><h3>Import an API definition</h3><p>Follow these <a href="https://docs.apimatic.io/getting-started/importing-api-spec/">instructions</a> to import your existing API definition or use the example <a href="https://gist.github.com/MaryamAdnan3/14186c9c1b0ac5d84b4f48368c7289f1">Petstore API.</a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/512/0*Zs6JxjhPOGyolH6_.png" /></figure><h3>Generate SDK Portal</h3><p>Follow these instructions to generate a portal for your SDKs using the API definition you just imported. In the last step, you’ll click “Preview API Portal.” A preview of your portal&#39;s default landing page will open in a new tab on your browser. From here onwards, you can customize or publish your portal’s look, feel, and behavior.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*9tALift7pnaDNzVC.png" /></figure><h3>Publish SDK Portal</h3><p>Click the Publish Portal button at the bottom of the page and follow <a href="https://docs.apimatic.io/publish-apis/hosting-your-portal/">these instructions</a> to publish a hosted portal.</p><p>Once publishing is complete, visit your unique URL to view your SDK documentation. You can also find the URL in the portal <em>Settings &gt; Publishing</em> section of the portal editor.</p><h3>Integrate APIMatic with Backstage</h3><p><em>Note: This guide assumes you already have an API Documentation portal with Backstage. For more details, visit their </em><a href="https://backstage.io/docs/getting-started/"><em>site</em></a><em>.</em></p><h3>Create a custom page for SDKs</h3><p>When completed, your Backstage developer portal will include a custom SDK page.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*jY1MVSwXVfFLGdq3.png" /></figure><p>After setting up the Backstage platform by following their <a href="https://backstage.io/docs/getting-started/">getting started guide</a> you’ll see your instance running at <a href="http://localhost:3000/">http://localhost:3000/.</a> Before running the application, ensure that the tech docs configuration section in app-config.yaml is configured to run locally.</p><p>The first step is to create a customized page in the Backstage platform. The page will include a list of all the supported language SDKs and links to setup instructions.</p><ol><li>For an overview on the docs-like code solution provided by Backstage, which is responsible for rendering documentation via markdown files, consult the <a href="https://backstage.io/docs/features/techdocs/">TechDocs</a> documentation.</li><li>Create a markdown file in your application’s doc folder, which you’ll find at <strong>&lt;root folder/docs&gt;</strong>, and provide a descriptive name <strong>&lt;doc name&gt;.md</strong>.</li><li>We’ve created a markdown template. Copy the <a href="https://gist.github.com/SidneyAllen/d856f3ef8ac925118bf3ce3f16980aa6#file-sdks-markdown-raw">markdown from here</a> and paste it into your markdown file. Note the text is for our Petstore example, so you can customize the text for your API. You must replace the YOUR_DOCS_SLUG and YOUR_API_KEY placeholders with the actual values for your SDK documentation. Detailed instructions are below.</li><li>YOUR_URL_SLUG represents the slug you defined when publishing your APIMatic Portal. To locate this value, hover over the top left corner of your API definition tile in the APIMatic Dashboard and copy the link. You will just need the subdomain of this URL e.g. <a href="https://your_docs_slug.apimatic.dev./">https://YOUR_DOCS_SLUG.apimatic.dev.</a> Replace all instances of YOUR_DOCS_SLUG with this value.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/474/0*JpUWkK3hkCmgn5Tl.png" /></figure><ol><li>YOUR_API_KEY represents a unique identifier for your SDK documentation. To access the API Key for your SDK documentation, click the kebab menu (three vertical dots) on the API definition tile to retrieve the API integration key.</li><li>From the context menu, select ‘API Integration Keys’.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/488/0*uxRgMpUrl8YwsIgG.png" /></figure><ol><li>Copy the property titled API KEY. In the markdown template, replace all instances of YOUR_API_KEY with this value.</li></ol><p>This concludes your setup for this custom page. Your new page lists all your SDKs. You can save your changes and proceed to the next step.</p><h3>Create a link to the custom SDK page</h3><ol><li>Create a mkdocs.yaml file in your application&#39;s root folder and change it to reference the markdown document in the navigation bar.</li></ol><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/31c70a11fc0ad07f6967b51dfd96a419/href">https://medium.com/media/31c70a11fc0ad07f6967b51dfd96a419/href</a></iframe><p>2. After running the application successfully, select <strong>Create</strong> from the navigation bar and press the <strong>REGISTER AN EXISTING COMPONENT</strong> button.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*yPMJTxjlzLtXzER_.png" /></figure><p>3. Import the catalog-info.yaml file and analyze it on the next page. The catalog-info.yaml file analysis will reveal any problems. Please take care of them before proceeding. You can read more about it <a href="https://backstage.io/docs/features/techdocs/creating-and-publishing">here</a>.</p><p>4. Provided the previous steps executed smoothly, you will see the <strong>VIEW THE COMPONENT</strong> button. Pressing this button takes you to a page with the newly created component details. Click on the <strong>DOCS</strong> tab to view the linked SDK documentation.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*IItnKGiUnS5I3d34.png" /></figure><h3>Embed APIMatic’s SDK Documentation in Backstage (Optional)</h3><p><em>This section is optional because your SDK documentation is already published and publicly accessible; embedding it in your Backstage portal is a nice touch but not a requirement.</em></p><p>In the previous section, we created a page that redirects to the SDK documentation hosted by APIMatic. We can go further and embed the SDK documentation inside a Backstage portal, and it would look like the following.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*8YJPO0-wBoD67BEg.png" /></figure><h3>Generate an APIMatic embed script</h3><p>APIMatic’s SDK Documentation can be embedded in any web page via an embeddable script. To generate the embed script for your APIMatic docs:</p><ol><li>Navigate to the APIMatic dashboard.</li><li>Locate your API definition tile.</li><li>Click Edit Docs to navigate to the Portal Editor.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/459/0*WSiJF6A2036xJ_Xl.png" /></figure><ol><li>In the top left corner of the Portal Editor, click the ‘Publish Portal’ button.</li><li>Choose the <em>Update Embedded</em> option on the next screen.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/474/0*MmUZcvoNd1Wh0A6G.png" /></figure><ol><li>Select the API version you want to generate the embed script for and click Generate Script.</li><li>You will be presented with a snippet containing the script. You need to copy this entire script to use in the next section.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/495/0*JeJSX5HDGxX9LNCj.png" /></figure><h3>Add Embed Script to Backstage Portal</h3><p>In the previous steps, we used APIMatic to create an embed script. Now include it in the Backstage portal.</p><p>First, we’ll create a customized page called SDKs that is accessible from the portal’s landing page. This new page displays our embedded portal links to the SDKs.</p><p>To achieve this please follow the instructions given in the Backstage official documentation of customizing the home page.</p><ol><li>We are modifying the default behavior of the application’s home page to link the SDK documentation. Create a new file HomePage.tsx. This is where our new homepage component will live. It will look like the following:</li></ol><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/1ee1be555bfa35c16e4b3978433c7318/href">https://medium.com/media/1ee1be555bfa35c16e4b3978433c7318/href</a></iframe><p>2. Now create a component with the name ApimaticWidget.tsx in the components folder of the Backstage application apps folder. This component will load the embedded portal by calling the <strong>initializeWidget</strong> method. The method uses the script copied earlier in the <a href="https://www.apimatic.io/blog/2024/01/apimatic-sdks-in-backstage-developer-portal#homepage-component">previous section</a>.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/79e2871b5f0277251b5c4244e3171ace/href">https://medium.com/media/79e2871b5f0277251b5c4244e3171ace/href</a></iframe><p>3. To make the portal accessible through an engaging information card, we will create another component with the name InformationCard.tsx.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/96df39d77b1ec362c3a24205f0d09863/href">https://medium.com/media/96df39d77b1ec362c3a24205f0d09863/href</a></iframe><p>4. Finally, let’s add the routes to the <strong>ApimaticWidget</strong> component in App.tsx to make the customized SDK page accessible from the navigation bar.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/e3f5a64f084da20d2b9b3a8fb4bd9703/href">https://medium.com/media/e3f5a64f084da20d2b9b3a8fb4bd9703/href</a></iframe><p>Now we have achieved an interactive and convenient way of making the SDKs even more accessible for the developers.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*293eCMydDDuWqQ9V.png" /></figure><p>Clicking on Petstore SDKs takes us right to an embedded APIMatic Portal without leaving our Backstage developer portal.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*YDtGMzS7vNiAjhBb.png" /></figure><h3>What’s Next?</h3><p>In the ever-changing landscape of API-driven development, combining Backstage’s API management capabilities with APIMatic’s automated SDK generation makes it easy for organizations to establish a strong foundation for API development and consumption.</p><p>If you liked what you saw in this blog, <a href="https://www.apimatic.io/account/register">sign up for APIMatic</a> and get started! We would love to see what you build with APIMatic. Tweet your updated Backstage Portals to us at <a href="https://twitter.com/apimatic">@APIMatic</a> or drop a mention on <a href="https://www.linkedin.com/company/apimatic-limited/mycompany/">Linkedin</a>.</p><p><em>Originally published at </em><a href="https://www.apimatic.io/blog/2024/01/apimatic-sdks-in-backstage-developer-portal"><em>https://www.apimatic.io</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7f763af2df47" width="1" height="1" alt=""><hr><p><a href="https://medium.com/apimatic/apimatic-sdks-in-backstage-developer-portal-7f763af2df47">APIMatic SDKs in Backstage Developer Portal</a> was originally published in <a href="https://medium.com/apimatic">APIMATIC</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[API Futures: Docs-Bots, API Assistants & OpenAPI Auto Fixing]]></title>
            <link>https://medium.com/apimatic/api-futures-docs-bots-api-assistants-openapi-auto-fixing-384b9e1ff64f?source=rss----f3aa4093ec86---4</link>
            <guid isPermaLink="false">https://medium.com/p/384b9e1ff64f</guid>
            <category><![CDATA[api]]></category>
            <category><![CDATA[apidocgen]]></category>
            <category><![CDATA[open-api]]></category>
            <category><![CDATA[ai-assistant]]></category>
            <category><![CDATA[api-documentation]]></category>
            <dc:creator><![CDATA[Adeel Ali]]></dc:creator>
            <pubDate>Thu, 15 Feb 2024 23:05:36 GMT</pubDate>
            <atom:updated>2024-02-15T23:12:35.626Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/873/1*eAd_WjJfec91eSBYlD5o_g.png" /></figure><p>2024 marks the first decade of APIMatic incorporation. That’s quite a lot of time being part of this beautiful community of API developer tools and witnessing the API industry evolving right in front. From new API description formats popping up to old ones fading away, from the love of HATEOAS to the rise and fall of microservices, the GraphQL storm, some big acquisitions and a few sad exits, tech alliances, patent fights, standardization efforts — it’s been an exciting rollercoaster!</p><p>Where is the industry heading in the future? From the learnings of a company focused on improving the developer experience of both API providers and consumers, we pick three active areas of innovation:</p><h3>1- API Docs-Bots to Massively Reduce Developers’ Onboarding Time</h3><p>API documentation solutions have come a long way in the past few years. Features like <a href="https://www.apimatic.io/blog/2020/06/the-anatomy-of-api-code-samples">runnable code samples</a>, and <a href="https://www.youtube.com/watch?v=eQNup8UicHw">guided walkthroughs</a> help developers get up and running quickly with an API. Still, a learning curve is involved before a developer can start writing the integration code.</p><p>In future, that learning curve and long API onboarding steps will likely be replaced by Generative-AI. For example, instead of going through each endpoint, reading the docs, and writing the code for authentication flow, a developer can ask a query to an “API Docs-Bot” in natural language, and get the integration code for the desired use case in a few seconds.</p><h3>What About Code Reliability?</h3><p>At the moment, Gen-AI is good at generating syntactically correct code, but it lacks the understanding of the semantics. Therefore, a challenge would be training the AI-bot to generate production-ready integration code for different scenarios. A couple of ways to solve this problem are using:</p><ol><li><strong>An expert developer</strong>: to feed detailed prompts to Gen-AI, and keep refining until the integration code of a desired quality level is returned. It is manual and hard to scale.</li><li><strong>A sophisticated code generator for APIs</strong>: to train the AI on the SDK of an API so that its responses are based on deterministically produced code by the code generator.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/869/0*s3q8EQLZcgLc5WDD" /></figure><p>To test the solution # 2, we’ve conducted a few experiments using APIMatic, and the initial results of creating an API Docs-Bot by combining the two machines have been quite promising (see the demo video below). Expect to see similar attempts in 2024 by API solution providers.</p><p><a href="https://www.apimatic.io/hubfs/chatbot%20demo.mp4">https://www.apimatic.io/hubfs/chatbot%20demo.mp4</a></p><h3>2- AI Assistants to let Non-Developers Play with APIs</h3><p>Developers or non-developers, we all use APIs. The difference is, developers build apps using APIs, while non-developers use APIs via those apps. Moreover, developers can use an API for countless use-cases, while non-developers can only try limited use-cases built in an app by a developer.</p><p>Imagine, I want to know how many times I went to restaurants in the past 12 months, what was the total expense, and the average cost per visit? Today, my options are</p><ol><li>to download and look manually into my bank statements, or</li><li>find a FinTech app which offers this functionality, or</li><li>get a developer to write an app using OpenBanking APIs.</li></ol><p>Later on, what if I want to see my top expense categories of the last 2 years as a graph? Again do it manually, or stay dependent on the functionality built by a developer.</p><p>The good news is that Gen-AI is quite capable of removing this dependency, i.e. letting non-developers access an API the way they want without needing a developer in the middle using AI assistants. Because of its conversational nature, the end users can easily provide their input in natural language, and further refine the output conversationally if needed.</p><p>In 2024, we expect to see a plethora of AI-assistants. However, similar to the API Docs-Bot case, training the Gen-AI to reliably access data from an API and converting that into information takes a considerable amount of time. A quicker way would again be using a code generator to reliably and instantly get the integration code, and train the AI to process the data coming through the APIs.</p><p>During the recent holidays, we experimentally built a financial assistant using Payments New Zealand’s <a href="https://www.apicentre.paymentsnz.co.nz/">OpenBanking APIs</a>. Here are a couple of queries in the screenshot below to depict the outcome (the sandbox data has been expanded to try different scenarios):</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*WGw6AjTm_LdCCrQJ.png" /></figure><h3>3- Governance — from OpenAPI Ratings to OpenAPI Fixing</h3><p>As the significance of API governance and design continues to grow, we see some new tools arriving in the market with a focus on assessing the quality of an API through its API definition. Two noteworthy examples include Zuplo’s <a href="https://ratemyopenapi.com/">Rate my API</a> and Trebble’s <a href="https://apiinsights.io/">API Insights</a>. Both tools audit API definitions against certain standards/conventions and then assign them a good/bad score for various categories including design, security, completeness and more. By highlighting specific areas of improvement, these tools empower API designers to make their definitions flawless. At APIMatic as well, we try to help API designers make their definitions better for stronger SDK and documentation generation. Following is what a audit snapshot of a typical OpenAPI with some validation and linting issues usually looks like:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/606/1*U4kxeRTkQPu8taf4KZon_w.png" /><figcaption>Audit summary of an OpenAPI definition file — auto-generated by APIMatic</figcaption></figure><h3>Why is a Flawless API Definition Important?</h3><p>GIGO (Garbage In, Garbage Out) is a familiar slang in the computer science world, meaning a flawed input would produce a nonsense output. GIGO is perfectly applicable to the processes needing OpenAPI definitions as the input. If you’re looking to <a href="https://caseysoftware.com/blog/how-chatgpt-will-solve-all-api-problems-except-yours">feed your OpenAPI definition to Gen-AI</a>, want to generate Docs, SDKs or do anything else, you either ensure a flawless API definition or don’t mind piling up some garbage. This problem is not new for API definition files (see some common mistakes from 2018 in <a href="https://www.apimatic.io/blog/2018/03/common-mistakes-developers-make-in-their-openapi-3-files">OpenAPI</a>, <a href="https://www.apimatic.io/blog/2018/09/common-mistakes-developers-make-in-their-api-blueprint-files">APIBlueprint</a> and <a href="https://www.apimatic.io/blog/2018/04/common-mistakes-developers-make-in-their-raml-files">RAML</a> definitions), but it is growing in magnitude and demands immediate attention. Based on APIMatic users we saw:</p><ul><li>20% of the total OpenAPI definitions brought to APIMatic violated OpenAPI standards and failed during the import process, whereas</li><li>50% of them conformed to OpenAPI standards but lacked the elements required to generate viable integration code.</li></ul><h3>Towards a Future of Auto-Fixing</h3><p>While an audit report helps identify the issues, somebody still has to fix those problems. This is the hard part due to the time and resources one requires to rectify a complex OpenAPI definition, especially if they are not too familiar with the syntax. Can AI help with the auto-fixing? Yes, but the reliability will remain a question unless somebody pays to train like an LLM. Till then, OpenAPI experts or man-made machines with pre-defined rules will keep on helping the API designers.</p><p>Therefore in 2024, we expect to see the audit tools moving a step forward, and help designers with (semi) automatically fixing the issues. At APIMatic, we’re running a movement with the name “<a href="https://www.apimatic.io/blog/2023/10/fix-my-openapi-vs-code-extension">Fix My OpenAPI</a>”, primarily focused on SDK and Docs generation. There is a free-to-use VS Code extension that comes with over 1200 predefined out-of-the-box rules. It not only ensures strict adherence to API standards but also recommends improvements and best practices to enhance one’s API definition. Moreover, there is an “auto-fix” feature in the extension to help remove some pesky issues with just a few clicks.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/643/0*1s57BbDrET7xTF3B.png" /></figure><p>That’s it for today. Let’s see what new and improved tooling 2024 brings up to help API designers while they curate OpenAPI definitions, and how far does the Generative-AI wave take the API space. Feel free to reach out at <a href="/service/mailto:adeel@apimatic.io">adeel@apimatic.io </a>for any feedback, or if you want to try out the Gen-AI POCs mentioned in this blog. I also want to acknowledge team APIMatic especially <a href="https://www.apimatic.io/blog/author/muhammad-saeed">Saeed</a>, <a href="https://www.apimatic.io/blog/author/ali-raza">Ali</a>, <a href="https://www.apimatic.io/blog/author/faria-rehman">Faria</a> and <a href="https://www.apimatic.io/blog/author/sid">Sidney</a> for their valuable input and R&amp;D initiatives.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=384b9e1ff64f" width="1" height="1" alt=""><hr><p><a href="https://medium.com/apimatic/api-futures-docs-bots-api-assistants-openapi-auto-fixing-384b9e1ff64f">API Futures: Docs-Bots, API Assistants &amp; OpenAPI Auto Fixing</a> was originally published in <a href="https://medium.com/apimatic">APIMATIC</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Ready, Set, Golang! Introducing Code Generator for Go SDKs]]></title>
            <link>https://medium.com/apimatic/ready-set-golang-introducing-code-generator-for-go-sdks-8627b4fe4144?source=rss----f3aa4093ec86---4</link>
            <guid isPermaLink="false">https://medium.com/p/8627b4fe4144</guid>
            <category><![CDATA[sdk]]></category>
            <category><![CDATA[go]]></category>
            <category><![CDATA[generator]]></category>
            <category><![CDATA[openapi-specification]]></category>
            <category><![CDATA[golang]]></category>
            <dc:creator><![CDATA[Sid Maestre]]></dc:creator>
            <pubDate>Tue, 23 Jan 2024 07:16:30 GMT</pubDate>
            <atom:updated>2024-01-23T07:16:30.465Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*sYafc1j8mtQHiG_w.png" /></figure><p>We’re APIMatic.io. We generate strongly typed SDKs along with a complete API reference from OpenAPI definitions. If you want to create an SDK for your REST API, check out how to <a href="https://www.apimatic.io/blog/2022/08/how-to-create-sdks-for-your-api-in-less-than-a-minute/">generate one in under a minute</a>. We support generating SDKs for C#, Java, PHP, TypeScript, Python, Ruby, and now Golang using the APIMatic Code Generator.</p><p>We are excited to announce that our new Go SDK Code Generator is now available as an alpha release. According to the StackOverflow <a href="https://survey.stackoverflow.co/2023/#most-popular-technologies-language-prof">Developer Survey 2023</a>, Go is used by ~14% of professional developers worldwide and is ranked amongst the top most admired languages by developers. Developers appreciate Go for its <a href="https://www.apimatic.io/blog/2023/04/how-gos-simplicity-brings-complexity">simplicity</a>, speed, cross-compilation support, concurrency primitives, and expansive standard library. Go developers commonly use it to create distributed network applications, cloud-native services, and standalone tools and utilities. Using the new APIMatic Code Generator, API Providers can now make their APIs accessible to Go developers by generating strongly typed, idiomatic Go SDKs for their API.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/156/0*t9S2w9dZwGW35n-W.png" /></figure><p>In this blog, we will take a look at the design of the Go SDKs generated by APIMatic. We will especially focus on how they help improve the developer experience, reduce onboarding time, and simplify integration code for API developers. We will also check why APIMatic’s Code Generation solution, especially for Go, stands out among the <a href="https://sdks.io/docs/ways-to-build-sdks/">various options for creating SDKs</a>.</p><h3>A Quick Tour of the Go SDK</h3><p>Let’s check out what the new Go SDKs generated by APIMatic Code Generator look like. These examples are from an SDK generated for a model payment API we call <em>IdealPay</em> and help illustrate the Go SDK usage experience.</p><h3>Making an API Call</h3><p>The Go SDK wraps the API into a Go-native interface while hiding away all the nitty gritty details of making an API call. JSON request and response bodies become Go structs. API calls become method calls. Authentication and error handling are built into the SDK and require minimal effort on the part of the developer to use. All this adds up to a developer experience that reduces the need for the Go developer to go back and forth between the API reference and the code editor as they figure out how to integrate the API into their application.</p><p>Let’s check out a code snippet that shows an API call being made using the Go SDK:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/0*tH57q_UKC-hkx51v.png" /></figure><p>APIMatic takes a batteries-included approach to the Go SDK design, reducing the effort needed by the API developers to write production-ready code by providing commonly used features such as:</p><ul><li><strong>Concurrency Support</strong>: The client is designed to be immutable. This allows the client instance to be shared between multiple threads without running into race conditions.</li><li><strong>Timeout and Retries</strong>: The SDK is designed to be resilient. Intermittent API call failures are handled by retrying the API calls based on an exponential backup algorithm. Non-responsive HTTP calls are timed out safely to release resources.</li><li><strong>Context-Aware Calls</strong>: The SDK allows the caller to pass “context”. This allows the SDK to be used in network applications where an API call might need to be canceled whenever a parent request is canceled.</li></ul><h3>Working with Request and Response Data</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/187/0*l-tlPI5Tymt2kmKV.png" /></figure><p>The generated Go SDK provides a <em>strongly typed</em> interface for making API calls by providing Go types for all API requests and responses. In the Go language, this means providing structs, enums, and interface types that help the developers provide the right data to the SDK when making API calls. The Go SDK then converts this data into the right API call by serializing the data as JSON, XML, or form data. However, the developers are oblivious to this detail as the SDK does the heavy lifting of creating the right API call saving the developer from having to read the API reference docs.</p><p>The code snippet below shows the request data being passed to the SDK during an API call. Check out how the Go SDK exposes a neat Go-native interface for handling various request data types:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/0*wJnymKelC9DnuQdR.png" /></figure><p>Since the response data is also strongly typed, the Go developer can quickly introspect the response type using their IDE’s auto-complete or type-hint functionality. Check out how VS Code hints at the available properties in the PaymentLink response:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/608/0*fw9a8bdSII4hdcJi.png" /></figure><p>Strong typing in both request and response helps catch code errors early in the development process by restricting the data types that can be exchanged with the SDK. The compiler raises errors during development which helps the developer correct mistakes, thereby eliminating an entire class of bugs from reaching the production environment.</p><h3>Documentation and Code Samples</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/225/0*z5cVR98MwF-IC-HN.png" /></figure><p>APIMatic not only generates the Go SDK but also supports creating a complete <em>SDK Reference </em>documentation in the shape of a website. This website contains the following for Go SDK and other generated SDKs:</p><ul><li>Installation and usage instructions for the SDK</li><li>Endpoint reference</li><li>Request and response type reference</li><li>⭐ Code samples showing API calls using Go SDK</li><li>⭐ API Console to make API calls without leaving the website</li></ul><p>The screenshot below shows a reference documentation site that we have created for a Petstore API, showing documentation for the “Add Pet” endpoint using the Go SDK:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*I8jFrCPGH2MOM0-d.png" /></figure><p>Developers can copy the code samples from the documentation into their IDE to quickly integrate the API call into their application. Since these code samples use the Go SDK, they are <em>DRY (</em><a href="https://en.wikipedia.org/wiki/Don%27t_repeat_yourself"><em>Don’t repeat yourself</em></a><em>) </em>because they do not embed the entire API call implementation detail inside the code samples; that implementation along with the types needed for requests and responses are provided by the Go SDK.</p><p>While inside the IDE, developers benefit from the IDE “Intellisense” features which help surface the method, types, and documentation for the SDK. This helps speed up the build-and-test development loop for developers, improving developer experience:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/690/0*U0PlXbLCq5SymQFI.png" /></figure><h3>Why Choose APIMatic’s Code Generator for Go SDKs?</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/172/0*8iTMsLSHtUxz8EGD.png" /></figure><p>APIMatic’s newest support for the Go language helps advance our goal of building the most comprehensive platform for crafting API developer experiences. With 8 years of development and millions of SDK downloads under its belt, APIMatic Code Generator represents the most mature solution for API providers to <a href="https://www.apimatic.io/resource/modern-guide-to-building-sdks">create SDKs for their API Programs</a>.</p><p>Here’s why we think our newest Code Generator for Go SDKs stands out from the crowd:</p><ol><li><strong>Designed from scratch for Go</strong>: APIMatic takes a principled approach to SDK design focusing on creating strongly typed, <a href="https://sdks.io/docs/best-practices/design/idiomatic-code/">idiomatic SDKs</a> that make the developers feel at home. Go developers will appreciate the attention to detail we have put into crafting neat types and interfaces in the SDK aligned with Go’s language conventions. This includes the use of the new Generics feature to simplify interfaces, the presence of doc blocks to types and methods, and the locking of dependencies using Go modules.</li><li><strong>Strong OpenAPI Coverage</strong>: APIMatic’s Code Generator has expansive support for OpenAPI features, including polymorphic inheritance, multipart requests containing files, nullable and optional types, and authentication schemes such as OAuth 2. Our API Validator helps you get the most out of your OpenAPI definition by finding common issues including hard-to-detect semantic errors.</li><li><strong>Zero-maintenance SDKs</strong>: APIMatic’s approach to SDK generation helps significantly reduce the cost of ownership of SDKs and docs for API providers. Once you’ve published your SDKs, APIMatic will automatically provide updates and security fixes via the <a href="https://www.apimatic.io/blog/2023/06/core-libraries-in-sdks/">Core Libraries</a> that power our SDKs. Add APIMatic’s <a href="https://www.apimatic.io/solution/no-code-dx">documentation solution</a> and you have API and SDK references that stay up-to-date with your latest API definition changes.</li></ol><p>Just like this exciting new release, you can always depend on the APIMatic team to deliver awesome improvements to the SDKs and supporting API tools. Our recent releases include:</p><ul><li>Complete overhaul of the <a href="https://www.apimatic.io/blog/2023/06/core-libraries-in-sdks">core functionality of SDKs</a> resulting in leaner code and easier maintenance.</li><li>New documentation<a href="https://www.apimatic.io/blog/2023/06/codegen-settings-docs-got-a-makeover"> for Code Generation Settings</a> to help you discover all the ways you can customize your SDKs.</li><li>Integration <a href="https://www.apimatic.io/blog/2023/05/sdks-for-readme-users">guide for Readme</a> users to add SDKs to their documentation sites.</li><li>A community<a href="https://www.apimatic.io/blog/2023/04/say-hello-to-sdks-io-a-resource-for-sdk-builders"> for SDK creators</a> and developers to learn best practices for building SDKs.</li><li><strong><em>Coming soon:</em></strong><em> Expanding support for complex OpenAPI schemas like OneOf and AnyOf.</em></li><li><strong><em>Coming soon:</em></strong><em> Ability to fix OpenAPI definitions automatically.</em></li></ul><p>So what are you waiting for? Ready, set, Golang! 🎉</p><p>You can sign up for a free 14-day trial of APIMatic to generate a Go SDK for your API. During the trial, you can <a href="https://www.apimatic.io/blog/2022/08/how-to-create-sdks-for-your-api-in-less-than-a-minute/">generate SDKs and API Documentation</a> in all programming languages supported by the APIMatic platform.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/214/0*CaSDvOFFZebmx71h.png" /></figure><p><em>Originally published at </em><a href="https://www.apimatic.io/blog/2023/09/introducing-code-generator-for-go-sdks"><em>https://www.apimatic.io</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8627b4fe4144" width="1" height="1" alt=""><hr><p><a href="https://medium.com/apimatic/ready-set-golang-introducing-code-generator-for-go-sdks-8627b4fe4144">Ready, Set, Golang! Introducing Code Generator for Go SDKs</a> was originally published in <a href="https://medium.com/apimatic">APIMATIC</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Rev Your Engines: The SDK Generation Race is About to Begin!]]></title>
            <link>https://medium.com/apimatic/rev-your-engines-the-sdk-generation-race-is-about-to-begin-77875ca54349?source=rss----f3aa4093ec86---4</link>
            <guid isPermaLink="false">https://medium.com/p/77875ca54349</guid>
            <category><![CDATA[openapi-specification]]></category>
            <category><![CDATA[openapi-generator]]></category>
            <category><![CDATA[codegen]]></category>
            <category><![CDATA[code-generation]]></category>
            <category><![CDATA[sdk-generation]]></category>
            <dc:creator><![CDATA[Sid Maestre]]></dc:creator>
            <pubDate>Thu, 18 Jan 2024 23:33:51 GMT</pubDate>
            <atom:updated>2024-01-18T23:33:51.044Z</atom:updated>
            <content:encoded><![CDATA[<p>Hey, speed demons and code maestros! 🚀 Buckle up for an adrenaline-fueled race through the SDK generation landscape featuring the contenders: APIMatic, Speakeasy, and OpenAPI Generator. As a seasoned SDK builder in the API realm, I’m taking these powerhouses for a spin to determine which emerges as the ultimate champion.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*29iDvgci5coEgFxU.jpg" /></figure><h3>Today’s Race Schedule</h3><p>So, fellow code warriors, fasten your seatbelts and join me. Let’s determine which contender will take home the coveted checkered flag in this epic battle of code prowess! 🏁</p><blockquote><em>Disclaimer:<br>Some modifications were made to Lob’s OpenAPI definition to prepare for our race. We removed properties that are </em>beta<em> and </em>premium<em> and modified property values that are unique to a specific account, i.e., an ID for an existing object (template, address, etc.). This is advice we would provide a company to create runnable code snippets for all users. The modified version of Lob’s OpenAPI definition we used is </em><a href="https://github.com/SidneyAllen/lob-openapi/tree/sdk-generator-comparison/sdk-generator-comparison"><em>available here</em></a><em>.</em></blockquote><blockquote><strong><em>APIMatic</em></strong><em><br>We found two idempotency keys defined with similar names, </em>Idempotency-Key<em> and </em>idempdency_key<em>, resulting in a duplicate variable. We removed one of the idempotency_key parameters.</em></blockquote><blockquote><strong><em>Speakeasy</em></strong><em><br>Three arrays did not have the items attribute defined, so we corrected that and removed a script tag that blocked our test.</em></blockquote><blockquote><strong><em>OpenAPI Generator</em></strong><em><br>The merge_variables default value broke code generation, so we corrected this in our API definition.</em></blockquote><blockquote><em>You can put your API definition to the test with APIMatic.</em></blockquote><blockquote>Start your <a href="https://hubs.li/Q02g-QKy0">free APIMatic Trial Today</a></blockquote><h3>Pit Stop 1: Validation and Linting</h3><p>In the world of SDK racing, precision is key. Before we hit the track, we’re making a pit stop for validation and linting. Which SDK ensures a clean and error-free journey, smoothly navigating Lob’s API definition with its oneOf, allOf, and anyOf twists and turns? Let’s kick off the race by inspecting their linting and validation prowess.</p><h3>OpenAPI Generator</h3><p>In testing OpenAPI Generator, I found the validate command wasn’t very useful in surfacing issues. I recommend running the generate command to receive more complete linting and validation. The warnings centered on correcting reserved words, ignoring maxLength, pattern validation, and examples on the requestBody while acknowledging limitations around allOf support. Sadly, the warnings lack line information or suggestions to address these warnings.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/703/0*b1WqpLoFY9J3v7hT.png" /><figcaption>OpenAPI Generator Validation</figcaption></figure><h3>Speakeasy</h3><p>Speakeasy also provides a CLI with a validate command that works better than OpenAPI Generator. Their validation results are more readable with line information. Unfortunately, no suggestions for fixing issues are provided. I also received a warning: “X is potentially unused or has been orphaned.” My investigation found these warnings to be false positives.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/703/0*NADOkU7-BIEcup1O.png" /><figcaption>Speakeasy Validation</figcaption></figure><h3>APIMatic</h3><p>APIMatic’s validation provides actionable feedback for your API definition to improve code quality. Each warning includes details and links to documentation about the violation with suggestions for fixing it.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*J0pOKRvtK0OZxtQR.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*NigOGSx7oYXJsXhm.png" /></figure><h3>Building the Car: Code Generation</h3><p>Comparing SDK code generators in every language can be time-consuming. I’ve found from experience that strongly typed languages like C# and Java are suitable for uncovering issues other languages may let slip by. For this reason, I chose Java to compare the three generators.</p><p>SDK generators will let you pass if your OpenAPI definition is syntactically correct. You can generate code, but you’ll also see warnings that some aspects of your API definition could be problematic. To assist you, code generators will remove or ignore things in your API definition that may interfere with successfully generating code.</p><p>Why do SDK code generators allow you to proceed? It’s a choice that allows you to experience the tool and examine the output without requiring you to spend hours resolving warnings of varying severity.</p><p>Will you want to optimize your API definition before publishing your SDKs? Yes, and <a href="https://marketplace.visualstudio.com/items?itemName=apimatic-developers.apimatic-for-vscode&amp;ssr=false#review-details">APIMatic’s VSCode extension</a> with 1200 rules specifically around code generation is an excellent tool for the job.</p><p>For those still in the evaluation phase, don’t spend too much time optimizing your API definition, as each code generator enforces slightly different rules; you’ll go crazy trying to please them all.</p><p>Using Lob’s API definition, I successfully generated Java SDKs using each tool. 🎉</p><p>Speakeasy did have the following warnings during code generation.</p><ul><li>The component is potentially unused or has been orphaned.</li><li>Only enum types of string or integer are supported. Enum type won’t be generated and will be treated as base type</li><li>Enum is nullable but does not contain a null value</li><li>anyOf should only contain types which are compatible with each other, use oneOf if the response can only match one type at a time</li><li>anyOf will not be supported by Speakeasy, treating as oneOf</li><li>missing schema type for X component, but found properties treating as object</li></ul><h3>Starting Line: Code Compilation</h3><p>APIMatic compiled successfully without any errors or warnings. Unfortunately, both Speakeasy and OpenAPI generators generated SDKs that failed to compile with 32 and 100+ errors, respectively.</p><p>To keep the race going, I got behind Speakeasy’s car and pushed it. From my previous experiment, I found inline headers in the Petstore API broke Speakeasy, so I removed all referenced headers in Lob. To my surprise, the generated Java code with Speakeasy compiled.</p><p><em>Note: removing API features is not recommended, but it was necessary to continue our race.</em></p><p>Sadly, I couldn’t get OpenAPI generator past the failed compilation.</p><h3>Test Drive: Code Evaluation</h3><p>For this comparison, I created a sample application for APIMatic and Speakeasy to retrieve a list of addresses and print the address’s street, city, and zip code.</p><h3>APIMatic</h3><h3>Speakeasy</h3><p>The address list response uses a generic object to hold the data. Because the data structure is unknown, I utilized a JSON tree structure to traverse and access address details. While the resulting code works, it is a suboptimal experience for Java developers.</p><p>OpenAPI Generator failed to compile and, therefore, was not included in the test drive.</p><h3>Victory Lap: Documentation</h3><p>What type of documentation do I include in my comparison? Any docs generated to support the SDK code library, including a getting started guide, SDK reference, code samples, and use case guides.</p><h3>OpenAPI Generator</h3><ul><li>Parameters</li><li>Return type</li><li>Authorization</li><li>HTTP request headers</li><li>HTTP response details</li><li>Complete code sample</li></ul><p>OpenAPI Generator’s code samples look runnable, but I noticed the create methods would fail as new objects don’t set any initial values.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*-Z5cWhFAeW-ShATP.png" /></figure><h3>Speakeasy</h3><ul><li>Parameters</li><li>Response</li><li>Code Sample</li></ul><p>The code samples included in the SDK reference are complete files with import statements. Like OpenAPI Generator, the code samples look runnable, but when testing the listAddress method, the default parameters resulted in a 422 status code.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*mRtvB_s__36_TtkN.png" /></figure><h3>APIMatic</h3><p>In addition to a ReadMe, APIMatic provides a hosted developer portal. The portal includes API reference docs and an SDK reference for each language. It’s easy to navigate and explore the methods, models, enums, and exceptions supported by the SDK.</p><p>The developer portal includes interactive documentation. Modifying property values in the docs update code samples in real-time. You can make live API calls from the documentation, similar to a Postman collection. Lastly, code samples default to a condensed display, but through the config settings, can show a complete runnable code sample. While testing the code sample address list, it ran as expected.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*u81PErRQyseEIOPQ.png" /></figure><h3>Conclusion</h3><h3>Final Score Card</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*8OpeI0-nKwydpbHYoe7elA.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*YYRuefJZK8AolEPd.png" /></figure><p>It’s time to put your API definition to the test with APIMatic.</p><p>Your <a href="https://hubs.li/Q02g-QKy0">free trial</a> gives you access to all features to test the platform’s SDK generation capabilities.</p><p><em>Originally published at </em><a href="https://www.apimatic.io/blog/sdk-code-generator-comparison"><em>https://www.apimatic.io</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=77875ca54349" width="1" height="1" alt=""><hr><p><a href="https://medium.com/apimatic/rev-your-engines-the-sdk-generation-race-is-about-to-begin-77875ca54349">Rev Your Engines: The SDK Generation Race is About to Begin!</a> was originally published in <a href="https://medium.com/apimatic">APIMATIC</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Fix My OpenAPI: Validate, Lint, and Auto-Fix with APIMatic For VS Code]]></title>
            <link>https://medium.com/apimatic/fix-my-openapi-validate-lint-and-auto-fix-with-apimatic-for-vs-code-8e4ee13daab6?source=rss----f3aa4093ec86---4</link>
            <guid isPermaLink="false">https://medium.com/p/8e4ee13daab6</guid>
            <category><![CDATA[apimatic]]></category>
            <category><![CDATA[open-api]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[vscode-extension]]></category>
            <category><![CDATA[linter]]></category>
            <dc:creator><![CDATA[Faria Rehman]]></dc:creator>
            <pubDate>Wed, 13 Dec 2023 05:44:34 GMT</pubDate>
            <atom:updated>2023-12-13T05:44:34.521Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*m2OKVE0INjNAL4gdFlQwtg.png" /></figure><p>At <a href="https://www.apimatic.io/">APIMatic</a>, we <a href="https://medium.com/apimatic/top-api-specification-trends-2019-2022-ea0526789b86">process hundreds of thousands of API definitions every year</a> to transform specification formats and generate SDKs and Docs. Interestingly, a big chunk of those API definitions is syntactically correct, but not good enough to generate highly quality code. This is simply because OpenAPI and other popular API specification formats are not built with code generation in mind. We are thrilled to announce the release of our new VS Code extension which comes equipped with over 1200 pre-defined rules to help you effortlessly validate, lint, and auto-fix your API definition files and generate powerful SDKs and documentation.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*8yaX4QW0WtZ1SEF974V3sA.gif" /></figure><p>In this blog, we will discuss in detail why we built this extension in the first place and how it can help you in your API journey. Or if you’re eager to get started with the extension, here’s the big old download button:</p><p><a href="https://www.apimatic.io/cs/c/?cta_guid=f1397d84-5ced-498b-aac7-98306ccae344&amp;signature=AAH58kFpZ6iuDnEOfjizT9FrYyLzYHLIRA&amp;pageId=141118672670&amp;placement_guid=805f4e2e-3d14-484f-b1c7-dd27e3745362&amp;click=30af7a22-dacc-4734-9018-eadfeb073a21&amp;hsutk=bc33c90305f89bcc8817ad92b451eca4&amp;canon=https%3A%2F%2Fwww.apimatic.io%2Fblog%2F2023%2F10%2Ffix-my-openapi-vs-code-extension&amp;utm_referrer=https%3A%2F%2Fwww.apimatic.io%2Fblog&amp;portal_id=2052727&amp;redirect_url=APefjpEw-IzWd4EbdiNC5KR2pgAhK8MDpLDHwZU8F48Hzd7-BPgXzkxv2Ux12oybcpE0PPpNo2L7YxTscJV0A39BGI1nddxVwxpEG81S_esXYCD5fOXj9M43-Vh4YpLcPTu7sUZPGMnaWb3DNphS7k3MTNVHoa4NXzi6KNVI6HwgglUfmbggTL8P9wTBx5ufJD3SmQTZ5awM2qcgzgMfWjxkEfcGn0A2oeRsiR8UUB9Wk2U5H2_1cg-SsoVpuvYaIYK8CRGKKHNPcDlLOSV1AqCsFj_xnERjTZEW6MikjZt2VPE1DwySLG2xOXXeG0EyJU7UP-qZi_nklm-OX1BvhAicWtrJ7LLDVw&amp;__hstc=245086810.bc33c90305f89bcc8817ad92b451eca4.1692971644687.1701753155559.1702384240397.77&amp;__hssc=245086810.2.1702384240397&amp;__hsfp=3838443076&amp;contentType=blog-post"><strong>Download now from the Visual Studio Marketplace</strong></a></p><h3>Another Validator! But Why?</h3><p>This has been the most common question we’ve received so far. There are some great tools in the market, but they have a few shortcomings that make them less ideal for users focused on auto-generating SDKs from their API definitions. Those shortcomings include:</p><h4>No dedicated rulesets for code generation</h4><p>While the existing tools, such as Spectral, have some basic rulesets and plenty of third-party rulesets available in their platform, they do not provide any rulesets out of the box to validate API specifications for code generation purposes.</p><h4>No enforcement of mandatory standard checks</h4><p>API specification standards like OpenAPI make some rules mandatory using the MUST/REQUIRED keywords. Some of those rules are quite important, but, unfortunately, not all of them are enforced by available tools, possibly to provide greater flexibility.</p><p>Here’s one that disallows keys of reusable components from having anything other than alpha-numeric characters, dashes, periods, and underscores in them:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fww7eETORKszerCLPEwlww.png" /></figure><p>These keys/names play an important role when generating code. However, I’m able to easily get away with any character in my schema name without any related error/warning in Spectral:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/420/1*dP9gwTqLqpkPNZ3M1ty_1Q.png" /></figure><h4>Too much flexibility</h4><p>All validators including Spectral offer the ability to disable rules as required. In some scenarios, flexibility can be a good thing. But when it comes to generating code, knowing beforehand what rules can negatively affect your output if disabled, can be hard to determine and so this flexibility can be a double-edged sword. You can even end up disabling something important.</p><h4>Missing documentation</h4><p>Nothing is worse than running into a tricky issue and not having any documentation to help you understand it. Here’s an example of Spectral where documentation is unavailable for some of its messages:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*c49rm0pY4PMrvTJBq2u76Q.png" /></figure><h4>No contextual information for an issue</h4><p>Sometimes an issue’s message alone cannot convey enough information, especially when it is important to understand “how” that particular issue originated in the first place. None of the existing tools provide any extra information along with its messages.</p><h4>No support for auto-fixing common issues</h4><p>Several common issues (e.g. inline schemas) often just need simple removal or relocation of certain components in the API definition. Auto-fixing can in such cases greatly reduce the time it takes to bring the API definition to the final shape. Unfortunately, existing tools still lack advanced features like these.</p><h4>Lack of merge-aware validation</h4><p>API providers looking to release their microservices as a single unified service for consumers require merging their API definitions into one. Ensuring each API definition is valid before and after the merge is a crucial phase that is not supported by any of the tools out there.</p><h4>No support for REST formats other than OpenAPI</h4><p>Most validators like Spectral focus only on OpenAPI as it is the most popular and widely adopted API specification format. However, we’ve observed that <a href="https://medium.com/apimatic/top-api-specification-trends-2019-2022-ea0526789b86">other API specification formats are still in use</a> even if in the minority e.g. RAML, Postman Collections, API Blueprint, WADL, etc. These formats are not supported by any of the popular validators out there.</p><h3>Validation Reimagined — Diving deeper into APIMatic VS Code Extension</h3><h4>1 — Familiar UI</h4><p>Visual Studio Code is a platform that millions of developers are already comfortable with. APIMatic’s extension has been built with simplicity and efficiency in mind. It offers you dedicated views in the same familiar environment so you can quickly get started.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*WJ5eW3cPZ2Ie1AzAyQs19w.png" /></figure><h4>2 — Compliance with API specification standards</h4><p>We enforce all checks marked as mandatory by specification standards like OpenAPI. Such checks are also not configurable. This ensures that your API definition is not only compatible with APIMatic and its products but will work well with other tooling out there as well.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/882/1*mZrHKpm_X6ho__ca4wzFMg.png" /></figure><p>In total, we offer <strong>739 validation rules</strong> to check compliance, with <strong>329 rules targeting only OpenAPI definitions</strong>.</p><h4>3 — Out-of-the-box lint checks for code generation and general quality</h4><p>To ensure smoother SDK generation, DX portal generation, and API specification format transformation, we lint your API definitions against <strong>542 out-of-the-box lint rules</strong> with <strong>503 targeting OpenAPI definitions</strong> alone. These checks cover all common issues including prevention of inline schemas, ensuring better naming conventions, etc.</p><p>You can easily configure the lint process as per needs e.g. you can skip certain rules or even entire rulesets, override the default severity of the rules, and even <strong>add custom lint rules</strong>.</p><h4>4 — Support for auto-fixing common issues</h4><p>This being one of the unique offerings, our auto-fix feature in the extension lets you remove some pesky issues with just a few clicks:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*D0F4qEC4gWaYP0ToFBKR9Q.gif" /></figure><p>As I mentioned earlier, OpenAPI and other formats aren’t designed for code generation. One of the most common issues we see because of this is an abundance of inline anonymous schemas in API definitions that negatively impact SDK and DX portal generation. Most users we encounter who have such definitions are not always familiar with ways to tackle them efficiently. With auto-fixing, we aim to ease their workload by handling such fixes directly in their files, ensuring accuracy and preventing additional issues. This way they can focus on what matters.</p><h4>5 — Richer validation experience</h4><p>In addition to the basic validation support of showing messages in the Editor and Problems view, our extension also provides dedicated views that enhance your validation experience. These views offer improved issue comprehension and quicker access to the information you need, enabling you to address issues with greater efficiency.</p><p><strong>Validation Summary View — Get a birds-eye view of all issues</strong></p><p>This is a view that shows a complete overview of the validation status of your workspace.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*a4hBQk-uEQ1JNrH__cACwg.png" /></figure><p>From here you can:</p><ol><li><strong>Navigate easily through all validation messages</strong> which are <strong>grouped intelligently</strong> based on severity and whether they are validation or linting messages. Inside these groups, all messages targeting the same issue are grouped, aiding you in addressing all instances of the same issue before moving on to the next. This helps improve the overall efficiency.</li><li><strong>Generate reports</strong> in multiple formats (PDF, HTML, Markdown, JSON) for your external stakeholders.</li><li>View an <strong>overall score of your API workspace</strong> which roughly predicts how good or bad the output that you generate from this API definition is going to be.</li></ol><p><strong>Current Position Issues View — See in-depth context for all issues you are currently working with</strong></p><p>See the in-depth context for all issues you are currently working with.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*yo1ztK5YwwA7dMUoxhztOw.png" /></figure><p>This view helps show more context for all issues applicable at the current cursor position in the Editor. The information shown in this view includes:</p><ol><li>Issue <strong>message</strong>.</li><li><strong>Severity</strong> of issue.</li><li>The exact location of the issue in the file with the complete <strong>line number and position range</strong>.</li><li>A breadcrumb or JSON reference <strong>path</strong> to the component.</li><li>Key-value pairs containing contextual metadata to help understand <strong>how and why the issue originated</strong>.</li><li>A <strong>reference call tree</strong> that shows a nested list of components referencing the current component to help understand <strong>how the issue originated</strong>.</li></ol><p><strong>Learn More View — Understand what an issue means and its resolution</strong></p><p>Developers are all too familiar with issues that leave them scratching their heads in confusion. We understand that time is precious so we allow you to view details of an issue from within the extension in the Learn More view:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_OOSvVAtsZZigoNlIDzMCw.png" /></figure><p>This includes a detailed description of the issue to help you understand what the issue means and why it occurred as well as hints that can be followed for resolving it. We also list down all relevant external links that can be used to learn more about the issue if needed and much more.</p><h4>6 — Merge-aware validation</h4><p>APIMatic supports <a href="https://medium.com/apimatic/auto-merging-apis-and-microservices-specifications-to-ease-api-integration-fe18b5ba4e47">merging multiple API definitions</a>. To ensure a successful merge, it is required that each API definition involved is valid before and after the merge. This is a multi-layer validation process and is supported by our VS Code extension as well.</p><h4>7 — Multiple API specification formats supported</h4><p>The extension not only supports OpenAPI definitions but also has basic validation support for other API description formats including RAML, API Blueprint, WADL, WSDL, Postman Collections, Insomnia, HAR, etc.</p><h4>8 — Ability to transform API specification format</h4><p>The extension comes with built-in support for <a href="https://www.apimatic.io/solution/transformer">API Transformer</a> allowing you to effortlessly convert your API workspace to your chosen output format. For instance, you can convert from OpenAPI to Postman and more.</p><h4>9 — Better support for APIMatic users</h4><p>If you are already an APIMatic user, we let you build your API definition from within the extension to check if the API can be successfully exported into APIMatic. Once the API definition is ready, you can easily export it to your APIMatic Dashboard for SDK/DX portal generation without needing to leave the VS Code extension. The extension offers minimal version management as well by letting you replace an existing version or add new versions to the same API group entity.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vS1P5ZNG5oc66bf-RHFlaw.gif" /></figure><p>To configure APIMatic processes, you can easily add an APIMatic Metadata file with just a few clicks:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/852/1*AJzdlLTsRAaVExTzltdEog.png" /></figure><p>We support validating all APIMatic-specific files including custom rulesets, APIMatic Metadata files, etc. so you can avoid any common mistakes.</p><h3>What’s next?</h3><p>The VS Code extension is currently available in preview mode for our APIMatic users. We welcome you to try it out now:</p><p><a href="https://www.apimatic.io/cs/c/?cta_guid=f1397d84-5ced-498b-aac7-98306ccae344&amp;signature=AAH58kFpZ6iuDnEOfjizT9FrYyLzYHLIRA&amp;pageId=141118672670&amp;placement_guid=805f4e2e-3d14-484f-b1c7-dd27e3745362&amp;click=30af7a22-dacc-4734-9018-eadfeb073a21&amp;hsutk=bc33c90305f89bcc8817ad92b451eca4&amp;canon=https%3A%2F%2Fwww.apimatic.io%2Fblog%2F2023%2F10%2Ffix-my-openapi-vs-code-extension&amp;utm_referrer=https%3A%2F%2Fwww.apimatic.io%2Fblog&amp;portal_id=2052727&amp;redirect_url=APefjpEw-IzWd4EbdiNC5KR2pgAhK8MDpLDHwZU8F48Hzd7-BPgXzkxv2Ux12oybcpE0PPpNo2L7YxTscJV0A39BGI1nddxVwxpEG81S_esXYCD5fOXj9M43-Vh4YpLcPTu7sUZPGMnaWb3DNphS7k3MTNVHoa4NXzi6KNVI6HwgglUfmbggTL8P9wTBx5ufJD3SmQTZ5awM2qcgzgMfWjxkEfcGn0A2oeRsiR8UUB9Wk2U5H2_1cg-SsoVpuvYaIYK8CRGKKHNPcDlLOSV1AqCsFj_xnERjTZEW6MikjZt2VPE1DwySLG2xOXXeG0EyJU7UP-qZi_nklm-OX1BvhAicWtrJ7LLDVw&amp;__hstc=245086810.bc33c90305f89bcc8817ad92b451eca4.1692971644687.1701753155559.1702384240397.77&amp;__hssc=245086810.2.1702384240397&amp;__hsfp=3838443076&amp;contentType=blog-post"><strong>Download now from the Visual Studio Marketplace</strong></a></p><p>You can learn more about each of the extension features <a href="https://docs.apimatic.io/validate-lint-apis/vs-code-apimatic-extension/overview/">here</a> and<a href="https://docs.apimatic.io/validate-lint-apis/vs-code-apimatic-extension/overview/"> </a><a href="https://share.hsforms.com/1mgu-bRCIQFGOAzqALfaSbw17zw7">share any feedback</a>.</p><p>Anticipated future changes include, but are not limited to:</p><ol><li>Support for <a href="https://docs.apimatic.io/generate-sdks/overview-sdks/">generating SDKs</a> in one or more languages from within the extension.</li><li>Support for <a href="https://docs.apimatic.io/publish-apis/api-portal-overview/">publishing a DX portal</a> from within the extension.</li><li>Improvements to stability.</li></ol><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8e4ee13daab6" width="1" height="1" alt=""><hr><p><a href="https://medium.com/apimatic/fix-my-openapi-validate-lint-and-auto-fix-with-apimatic-for-vs-code-8e4ee13daab6">Fix My OpenAPI: Validate, Lint, and Auto-Fix with APIMatic For VS Code</a> was originally published in <a href="https://medium.com/apimatic">APIMATIC</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Introducing Core Libraries in SDKs]]></title>
            <link>https://medium.com/apimatic/introducing-core-libraries-in-sdks-fd61b030b2e9?source=rss----f3aa4093ec86---4</link>
            <guid isPermaLink="false">https://medium.com/p/fd61b030b2e9</guid>
            <category><![CDATA[apimatic]]></category>
            <category><![CDATA[swagger]]></category>
            <category><![CDATA[code-generator]]></category>
            <category><![CDATA[openapi3]]></category>
            <dc:creator><![CDATA[Mehdi Raza]]></dc:creator>
            <pubDate>Mon, 03 Jul 2023 16:52:23 GMT</pubDate>
            <atom:updated>2023-07-03T16:52:23.042Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*L9idV7aoU4eoRXS87DQ0jA.jpeg" /></figure><blockquote>We’re <a href="https://www.apimatic.io/">APIMatic.io</a>. We generate strongly typed SDKs along with a complete API reference from OpenAPI definitions. If you’re looking to create an SDK for your REST API, check out how to <a href="https://www.apimatic.io/blog/2022/08/how-to-create-sdks-for-your-api-in-less-than-a-minute/">generate one in under a minute</a>. This post covers a major enhancement to the design of our generated SDKs, aligned with our mission to provide zero-maintenance SDKs to API providers.</blockquote><p>In this release, we have majorly revamped SDKs to improve the code quality, reduce code size, and provide better test coverage than ever. At the center of these changes are the new <strong>Core Libraries </strong>which now help power the SDKs and provide many new quality of life improvements for SDK users. Despite these improvements, we have taken care to make sure that the SDKs have no breaking changes with this release.</p><h3>Why did we redesign our SDKs?</h3><p>Every SDK that we generated in the past contained some common utility code. This utility code which we often call the <strong>SDK Internals</strong> provided functionality like the ability to create HTTP requests, handle responses, facilitate authentication, convert API responses back to class instances, and validate user and server data.</p><figure><img alt="What goes inside an SDK?" src="https://cdn-images-1.medium.com/max/1024/1*oJH7oF_Qpzjv04pxUyOazg.png" /></figure><p>So even though the most interesting part of the SDK are the endpoint methods and the models (a.k.a. data classes) which are part of the <strong>SDK’s Interface</strong>, these work by building on top of the SDK Internals which do all the heavy lifting needed to make the SDKs work<strong>.</strong></p><p>Not only do SDK Internals themselves contain significant logic for making API calls happen, they also pull in dependencies to help power the SDK functionality. For example, they can pull in an HTTP client library to help make the HTTP calls for the API, or perhaps a JSON serializer library to help convert Data Objects to and from JSON.</p><p>This makes SDK Internals a crucial part of the SDKs on which the rest of the SDK’s work depends. To ensure that the SDK keeps working, we need to provide updates for the SDK Internals, the kind of updates that fix bugs, patch vulnerabilities and provide other improvements to the SDK.</p><p>However, that’s where we run into a limitation with our previous design.</p><figure><img alt="Can we improve our SDK design?" src="https://cdn-images-1.medium.com/max/1024/1*vjuL0zy5YXijXf5Q3rf0sQ.png" /></figure><p>The SDK Internals were part of the SDKs. This meant that fixing them required generating a new SDK as well. Even when an API provider did that, this would only get them an updated SDK for the latest version of their API. Meanwhile all the old SDK versions that are still used by the API users contain SDK Internals that might need to be updated for vulnerabilities or bug fixes.</p><p>Generating new SDKs everytime a small bug fix or dependency update needs to happen multiplied for every SDK version is definitely impractical for API providers! So we set about to solve this problem with a redesign.</p><h3>What are Core Libraries?</h3><p>That is where Core libraries enter the game.</p><figure><img alt="What are Core libraries?" src="https://cdn-images-1.medium.com/max/1024/1*-rlaiVdifg5wmFViztlVkQ.png" /></figure><p>The solution to our code duplication problem was simple. We redesigned the SDKs so that all SDK Internals that were previously part of the SDK itself are now externalized into a library, the <strong>Core library</strong>, which is installed into the SDK just like any dependency (more on that later).</p><p>This means most of the code inside the SDKs now consists of code that is specific to the API. This usually consists of the endpoint methods and data models that are generated by the APIMatic Code Generator using the OpenAPI definition. The SDK Internals was code that stayed mostly unchanged from SDK to SDK is no longer part of the SDK code base.</p><p>This dramatically reduces the amount of code that is present in the generated SDKs. This helps us provide even better care of the generated SDKs by taking charge of when and how Core libraries are updated. Let’s see how that happens.</p><h3>Core Libraries keep your SDKs fresh</h3><p>With SDK Internals code out of the SDK and into a Core Library, you must be wondering who is responsible for maintaining the Core Library and updating it. APIMatic’s team, of course!</p><figure><img alt="Who updates the SDKs and the Core libraries?" src="https://cdn-images-1.medium.com/max/1024/1*H2tBHdKgn3mHtgl7ZoyGzA.png" /></figure><p>All SDKs use the latest Core Libraries by installing them via the <strong>package repository</strong>. A package repository is a public database where library authors publish their libraries for anyone to use. For example, npm for Node.js or Pypi for Python are the de facto package repositories for their respective languages. APIMatic maintains the Core Libraries and publishes new versions of them to the package repositories whenever there is an update. These updates then make it into the SDKs by virtue of the SDKs depending on the latest version of the Core Library.</p><p>This solves a big problem in the maintainability of the SDKs: how to update both new and old SDKs.</p><figure><img alt="How Core libraries help SDKs stay updated after release?" src="https://cdn-images-1.medium.com/max/1024/1*t4KnkB3Qc-haK-2HjpdOew.png" /></figure><p>Whenever APIMatic fixes a vulnerable dependency or makes some performance improvement, these automatically make it into all the SDKs without the need for anyone to generate a new SDK from our Code Generator. This means that we are able to push updates and fixes faster than ever before without any additional effort from the API providers.</p><h3>Core libraries help deliver updates to the SDK</h3><p>Let’s dive a little deeper into the kind of updates Core libraries receive:</p><ol><li><strong>New features</strong>: These include new functionality in the SDK such as API call retries or HTTP caching. Often functionality like this also requires a new SDK to be generated.</li><li><strong>Improvements</strong>: Smaller changes like improved error messages were made available to the users without the need to update their SDKs. Improvements to HTTP calls, JSON serialization and validation happen frequently.</li><li><strong>Language updates</strong>: Most languages see new version releases every year. To help make sure that your SDK continues to work on a new language runtime, we provide compatibility updates to our Core libraries as well as our SDKs when needed.</li><li><strong>Bug fixes</strong>: These include patches to issues reported by our customers.</li><li><strong>Dependency updates</strong>: Libraries used by the Core library to make HTTP requests or serialize JSON see frequent updates. These updates can help introduce new features or performance improvements, for example updates to the HTTP client to introduce HTTP/3 support.</li><li><strong>Vulnerability fixes</strong>: Third-party dependencies require patches from time to time. We track such vulnerabilities using a vulnerability scanner and alert tool and provide updates when available.</li></ol><h3>Core Libraries improve SDK maintainability</h3><p>Core libraries help push updates and improvements to old and new SDK versions automatically, improving the maintainability of the SDKs. However, while working on Core Libraries, we used this opportunity to improve the code that goes inside the SDK as well.</p><p>As we designed the Core libraries, we thought about what a clean interface between the SDK and the Core library would look like. For us, a clean interface meant that the SDK contained only code that was necessary for the SDK to function and specific to the API for which the SDK was generated for. All other code should be delegated to the Core libraries which should provide the implementation details for the SDK.</p><p>With this goal in mind, we were able to majorly revamp our implementation code for API calls. Checkout a sample of what an endpoint method (method that makes an API call) looks like in a generated Java SDK before and after our redesign:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*iQvrDyvVNpbDo-BmxamgdA.png" /><figcaption>Comparing an API call implementation in the Java SDK before and after Core Libraries</figcaption></figure><p>That’s almost half the code! This coupled with redesigning the SDKs so that most of it consists of declarative code that is implemented using Core Libraries has had a positive effect on the testability of the SDK as well.</p><figure><img alt="How Core libraries improve SDK test coverage?" src="https://cdn-images-1.medium.com/max/1024/1*8cKIJWW7GBMrwvnm3wvw1g.png" /></figure><p>These test suites are part of the Core Libraries’ codebases and can be viewed on GitHub. For example, checkout the test coverage numbers in PHP’s Core library:</p><figure><img alt="Test coverage numbers in PHP’s Core library" src="https://cdn-images-1.medium.com/max/1024/1*q72LrX0TeAwiIgVoFctAow.png" /></figure><h3>Core Libraries provide an Open-Source core for the SDKs</h3><p>Having the source for the Core libraries published on GitHub allows us to engage with a wider community of developers to gather bug reports and to get pull requests for fixes and new features. It also provides visibility to the public into the test suites that we run to maintain our projects, something that was not previously available outside of APIMatic. That means the SDK users can now refer back to the code that powers their SDK and submit improvements for it.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*TB7Zr_1xevS-Xh9NHF7BDA.png" /><figcaption>Screenshot from GitHub showing the PHP Core library repository</figcaption></figure><p>We follow all the best practices expected of a Open Source library such as:</p><ul><li>Continuous testing via our test suites and GitHub Actions</li><li>Checking code quality through linting and static analysis checks</li><li>Tracking maintainability through Code Climate</li><li>Vulnerability checks and alerts via Dependabot</li><li>Open collaboration via a permissive MIT license</li></ul><p>We are also excited about the possibilities of having alternative implementations for some of the functionalities provided by the Core library, thanks to modularization of the SDK through Core libraries and the fact that this code is now open source.</p><figure><img alt="How Core libraries allow fflexibility in dependencies?" src="https://cdn-images-1.medium.com/max/1024/1*o12pfUE_JbQZcOqlmo6l1w.png" /></figure><p>This creates the opportunities for API providers and SDK users to customize SDKs for their specific needs to meet their business requirements. Think HTTP clients that integrate neatly with their web framework of choice or serialization libraries that integrate directly with the Dependency Injection framework they use.</p><h3>Summary</h3><p>This release represents one of the biggest refactoring of the SDKs generated by APIMatic. We have redesigned the SDKs for all of the currently supported languages in our Code Generator. This means when you generate the SDKs now, they will be using the new design and will depend on the Core Libraries to provide their functionality.</p><figure><img alt="SDKs using Core libraries" src="https://cdn-images-1.medium.com/max/1024/1*zynBdm-WpSFgBQDKmCO-Wg.png" /></figure><p>Core libraries have not only improved the SDK quality story but will help us iterate even faster in the future. If you haven’t tried out APIMatic’s Code Generator, <a href="https://www.apimatic.io/blog/2022/08/how-to-create-sdks-for-your-api-in-less-than-a-minute/">do try it out</a> and let us know what you think.</p><p><em>Originally published at </em><a href="https://www.apimatic.io/blog/2023/06/core-libraries-in-sdks/"><em>https://www.apimatic.io</em></a><em> on June 27, 2023.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=fd61b030b2e9" width="1" height="1" alt=""><hr><p><a href="https://medium.com/apimatic/introducing-core-libraries-in-sdks-fd61b030b2e9">Introducing Core Libraries in SDKs</a> was originally published in <a href="https://medium.com/apimatic">APIMATIC</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Introducing the Art of Developer Experience Podcast]]></title>
            <link>https://medium.com/apimatic/introducing-the-art-of-developer-experience-podcast-a63a313925af?source=rss----f3aa4093ec86---4</link>
            <guid isPermaLink="false">https://medium.com/p/a63a313925af</guid>
            <category><![CDATA[api]]></category>
            <category><![CDATA[podcast]]></category>
            <category><![CDATA[dx]]></category>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[developer-experience]]></category>
            <dc:creator><![CDATA[Sid Maestre]]></dc:creator>
            <pubDate>Mon, 22 May 2023 16:48:12 GMT</pubDate>
            <atom:updated>2023-05-22T16:47:39.295Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ZhbNPn2SlEH0SPMUBNARxA.png" /><figcaption>Photo by <a href="https://unsplash.com/@willfrancis?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Will Francis</a> on <a href="https://unsplash.com/s/photos/podcast?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></figcaption></figure><p>What the heck is “Developer Experience in 2023?” This is one of the questions we ask our guests (of course more politely) to see what they think. It’s a fairly new term and one with competing definitions depending on the group using it.</p><p>Our guests are from leading technology companies and join me, <a href="https://www.linkedin.com/in/sidmaestre/">Sid Maestre</a>, to have authentic conversations about the challenges of creating products for a technical audience (often APIs) and discuss how DX is evolving. We dive into topics like API design, documentation, SDKs, tooling, developer relations, dashboards, metrics, and more.</p><p>We hope to spark ideas for ways you can improve the developer experience at your company.</p><p>Subscribe on the following Podcast platforms</p><ul><li><a href="https://open.spotify.com/show/2MS2PLJguybMvhj04oLJ88">Spotify Podcasts</a></li><li><a href="https://podcasts.apple.com/us/podcast/the-art-of-developer-experience-podcast/id1685931474">Apple Podcasts</a></li><li><a href="https://music.amazon.com/podcasts/a4bff122-f314-40f9-aee7-f66d26673440">Amazon Music</a></li></ul><p>In our first episode we ask Richard Fortune who spent the better part of a decade working on Xero’s developer platform what is developer experience.</p><p>“<em>When I join a new organization or introduce someone to an organization, they often have a lot of questions around what developer experience is. If you Google it, you’ll find it defined as UX for developers, but I think it’s a bit blurrier than that in the real world.</em></p><p><em>For me, developer experience is all about the journeys that people take when trying to connect to systems. As someone who has worked on the platform side repeatedly, I think it’s important to make that journey as easy as possible to help developers achieve success quickly. It’s important to consider what role they are playing when they’re building with you on that particular day, and that’s a really important first step. If you do that well enough on the first cut, it’s important to do it repeatedly on all the other stages of the journey. This really works well when you have additional offerings later on as well.</em>“</p><p>In episode two, Brian Rinaldi from Launch Darkly shares his thoughts on the term developer experience.</p><p><em>I completely agree that developer experience is a broad and vague term and it varies from company to company. At LaunchDarkly, my focus as a developer experience engineer is to make it easier for developers to onboard and use our product. This includes providing resources and tools to help streamline the process and improve the learning curve. Documentation is a significant aspect of developer experience, and I contribute to our docs even though we have a dedicated docs team. While some companies may focus more on developing tools to ease the onboarding process, my role is more content-focused.</em></p><p>We chatted with Luke Kilpatrick in episode three and addressed the elephant in the room with two diverging definitions of the term developer experience.</p><p><em>The concept of developer experience has evolved into two different flavors. The first is external-facing, focused on helping external adopters of a company’s API, tool or ecosystem through developer marketing and relations. The second flavor, focused internally, has emerged from companies like Netflix and is aimed at improving the developer’s experience in writing code and getting it into the CI/CD pipeline. This includes onboarding and platform engineering. While this is a positive development, it has caused some confusion about what developer experience is and what directors of developer experience do.</em></p><p>Thanks for subscribing, new episodes released every two weeks.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a63a313925af" width="1" height="1" alt=""><hr><p><a href="https://medium.com/apimatic/introducing-the-art-of-developer-experience-podcast-a63a313925af">Introducing the Art of Developer Experience Podcast</a> was originally published in <a href="https://medium.com/apimatic">APIMATIC</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How Go’s Simplicity Brings Complexity]]></title>
            <link>https://medium.com/apimatic/how-gos-simplicity-brings-complexity-7594f909a3a4?source=rss----f3aa4093ec86---4</link>
            <guid isPermaLink="false">https://medium.com/p/7594f909a3a4</guid>
            <category><![CDATA[go]]></category>
            <category><![CDATA[programming-languages]]></category>
            <category><![CDATA[golang]]></category>
            <dc:creator><![CDATA[Sid Maestre]]></dc:creator>
            <pubDate>Tue, 02 May 2023 18:17:57 GMT</pubDate>
            <atom:updated>2023-05-02T18:17:38.630Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vhzzwk0uMwap9gsbpiiJ3w.jpeg" /><figcaption>Photo by <a href="https://unsplash.com/@parrish?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Parrish Freeman</a> on <a href="https://unsplash.com/photos/4rF9RftX4XA?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></figcaption></figure><p><a href="https://go.dev/">Golang</a>, aka Go, is a modern programming language known for its simplicity, ease of use, and ability to handle high-concurrency tasks. However, this simplicity can sometimes bring complexity to the code you write. As a software developer, I learned this while delving deeper into coding with Go.</p><p>Transitioning to a new programming language can be challenging, and Go is no exception. In this article, I’ll explore some of the challenges I faced when migrating to Go from another language.</p><h3>Navigating the Unintended Complexity in Go</h3><h4>Go-ing Beyond Static Typing: Implementing Polymorphism</h4><p>The most prominent area (in my experience) where Golang’s simplicity can cause complexity is in polymorphism. Other languages, like .NET, easily implement polymorphism using classes that inherit from a base class. But in Go, things work a little differently.</p><p>While Go has polymorphism, it is limited to interfaces only. This means developers have to create interfaces for every structure they build and make sure each class implements those interfaces. This introduces complexity when dealing with polymorphic JSON structures.</p><p>I encountered complexity while implementing templates for generating APIMatic’s Golang client SDKs. API definitions with inheritance in their model structures require generated code that supports inheritance and polymorphism. It was a challenging task to work with arrays of polymorphic objects, but I discovered that using custom unmarshaling with a discriminator could help. This discriminator tells the unmarshaller which type of object it is dealing with, so it can convert the interface type into the correct object type and then call that object unmarshaller. unmarshal it.</p><h3>The Great Error Hunt in Go</h3><p>Beyond polymorphism, there are other factors making the switch to Go a challenge. For example, Go has a unique style of handling errors. Instead of throwing simple exceptions like other languages, Golang uses multiple return values and error codes. This means an error propagates till it reaches the code that invoked it. This approach leads to more explicit error handling, but it is more verbose and requires implementation of additional error-handling logic.</p><p>To illustrate, let’s look at some code with error handling.</p><pre>// GetLocationById returns Location Coordinates<br>// if the ID provided is valid else returns an error.<br><br>func GetLocationById(id int) (*Coord, error) {<br> if id &gt; 0 &amp;&amp; id &lt; 10 {<br>  return &amp;Coord{1, 2}, nil<br> }<br> return nil, errors.New(&quot;unknown id&quot;)<br>}<br><br>func main() {<br> coord, err := GetLocationById(344)<br> if err != nil {<br>  fmt.Println(&quot;An error occurred: &quot;, err)<br>  return<br> }<br> fmt.Println(&quot;Got the coordinates: &quot;, coord)<br>}</pre><h4><strong>Smelly Garbage Collection in Go</strong></h4><p>Among popular server-side programming languages, Go is unique in its use of a garbage collector to manage memory. This is an example of Golang providing simplicity to developers. While garbage collection makes memory management easier for developers, it also exposes risks of performance issues. If not managed properly, garbage collection can introduce additional overhead and latency. This is complexity for developers who write low-latency applications.</p><h4>Perils of Go’s Dependency Management System</h4><p>Go does not have a central dependency management system like other languages, and developers typically load dependencies straight from GitHub or any public platform. This makes it simple to work with, but you may spend more time searching for the right package to use.</p><h3>It isn’t all bad..</h3><p>While Go’s simplicity can create complexity in some areas, there are still many things to love.</p><h4>Simplicity in Access Modifiers</h4><p>I appreciate Golang’s simplicity when it comes to variable access modifiers. Unlike other languages, there are no specific access modifier keywords in Go. Instead, Go has a simple approach to access modifiers: capitalized means public and un-capitalized means private (outside package). This makes it easy to understand and manage the visibility of your code. Here’s an example of how simple access modifiers are in Golang:</p><pre>// There are only 2 access modifiers in Go; Exported(public) and Unexported(private).<br><br>type Sample struct {<br> PublicField   bool    // Public/Exported fields in Go have capitalized field names<br> privateField  string  // Private/Unexported fields in Go have lowercased first letter of the field name<br>}</pre><p>This simple naming convention ensures their code is easy to read and maintain, while still maintaining strong encapsulation.</p><h4>Go Generics: The Gift that Keeps on Giving</h4><p>In early 2022, Golang developers released <a href="https://go.dev/blog/intro-generics">Go generics</a>, which takes a lot of boilerplate code away, making code simpler and easier to work with. This feature allows developers to work with any type of data in a more efficient way.</p><h4>Go’s Multiple Returns for Cleaner Code</h4><p>One of the distinctive features of Go is the ability to return multiple values from a function. This allows developers to write clean and concise code that can handle multiple errors or return multiple values without having to resort to using structures or other data types.</p><p>This feature is particularly useful in error handling, where a function can return both a result and an error value at the same time, reducing the need for error-checking code throughout the application.</p><pre>type Coord struct {<br> Latitude  int<br> Longitude int<br>}<br><br>// GetLocationById returns Location Coordinates<br>// if the ID provided is valid else returns an error. <br><br>func GetLocationById(id int) (*Coord, error) {<br> if id &gt; 0 &amp;&amp; id &lt; 10 {<br>  return &amp;Coord{1, 2}, nil<br> }<br> return nil, errors.New(&quot;unknown id&quot;)<br>}</pre><h4>Code Styling is FTW!</h4><p>Go has a built-in tool called <a href="https://go.dev/blog/gofmt">gofmt</a>, which automatically formats code according to Go conventions. This makes it easy for developers to write clean, consistent code without having to worry about manually formatting it. Additionally, the Go vet tool can help identify subtle issues in code such as unreachable code areas. This helps developers catch errors early on and ensures their code adheres to Go’s strict coding standards.</p><h4>Go-odbye Unused Variables</h4><p>One of the key benefits of Go is its efficient memory management. Golang’s compiler does not allow unused variables in the code, which saves a lot of memory. This means developers cannot accidentally declare dead variables in their code which would consume memory. This helps reduce memory usage and ensure your Go applications run efficiently.</p><h3>It’s Time to Go Now</h3><p>Working with Go programming language has come with its fair share of challenges. However, I’ve relished the simplicity and efficiency that this language offers, enabling me to tackle complex tasks with ease. Now, with the power of Go generics, I’m beyond excited to get my hands on this new toolset, which I believe will revolutionize the way I approach coding.</p><p>Check out <a href="https://www.apimatic.io/blog/">APIMatic blog</a> section for more informative reads.</p><p><em>Originally published at </em><a href="https://www.apimatic.io/blog/2023/04/how-gos-simplicity-brings-complexity/"><em>https://www.apimatic.io</em></a><em> on April 18, 2023.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7594f909a3a4" width="1" height="1" alt=""><hr><p><a href="https://medium.com/apimatic/how-gos-simplicity-brings-complexity-7594f909a3a4">How Go’s Simplicity Brings Complexity</a> was originally published in <a href="https://medium.com/apimatic">APIMATIC</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[sdks.io — a place for SDK builders]]></title>
            <link>https://medium.com/apimatic/sdks-io-a-place-for-sdk-builders-f0a339669f6?source=rss----f3aa4093ec86---4</link>
            <guid isPermaLink="false">https://medium.com/p/f0a339669f6</guid>
            <category><![CDATA[api]]></category>
            <category><![CDATA[open-api]]></category>
            <category><![CDATA[openapi-generator]]></category>
            <category><![CDATA[sdk]]></category>
            <dc:creator><![CDATA[Sid Maestre]]></dc:creator>
            <pubDate>Tue, 25 Apr 2023 21:57:45 GMT</pubDate>
            <atom:updated>2023-04-25T21:57:56.638Z</atom:updated>
            <content:encoded><![CDATA[<h3>sdks.io — a place for SDK builders</h3><p>In this article, we’ll introduce you to <a href="https://sdks.io/docs/introduction/">sdks.io</a>, why we built it, and our hopes for the future.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*rloZw7JpAnB1UJLHljA17w.jpeg" /><figcaption>Photo by <a href="https://unsplash.com/es/@corinnekutz?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Corinne Kutz</a> on <a href="https://unsplash.com/photos/tMI2_-r5Nfo?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></figcaption></figure><h3>What are SDKs</h3><p>SDKs (software development kits) are collections of software development tools and resources that allow developers to create applications for a specific platform or operating system. SDKs can include libraries, sample code, and documentation, among other resources.</p><h3>Why SDKs are important</h3><p>SDKs are important for developers because they abstract away complexity and reduce the amount of code a developer needs to write when integrating with APIs. Companies provide these pre-built components and tools as SDKs making it easier for developers to build robust and feature-rich applications.</p><p>Additionally, SDKs can provide developers with support and documentation, which helps them troubleshoot issues and ensure their application is working as intended. This can be especially useful for developers who are new to a platform or who are unfamiliar with its specific tools and resources.</p><h3>What is SDKs.io</h3><p><a href="https://sdks.io/docs/introduction/">SDKs.io</a> is a site dedicated to improving the state of SDK development. <a href="https://www.apimatic.io/">APIMatic</a> has years of experience building SDKs for leading technology companies and our staff includes those who’ve managed SDK programs for API providers. We brought our combined experience together to establish a set of best practices developers can use to build SDKs for consuming RESTful APIs.</p><p>At SDKs.io we cover subjects such as design considerations before you start building, guidelines for constructing code libraries, and recommendations for supporting developers through different types of documentation. With this information teams are better equipped to provide software that serves their developer community.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*yzd09z9g5otiFEjn.png" /></figure><h3>Best Practices</h3><p>The <a href="https://sdks.io/docs/category/design">design section</a> helps teams think big picture and establish guidelines for developing code libraries that are the foundation for an SDK. In preparation, you’ll consider the programming languages and frameworks to support, does your API work for both client and server-side libraries, should you utilize code generation, and should you open source your SDK code. We discuss the importance of idiomatic code and naming conventions and how annotations can be used to power code completion in developer IDEs.</p><p>The <a href="https://sdks.io/docs/category/build">build section</a> dives deep into the details of building code libraries for APIs. We cover topics such as authentication, translating endpoints into methods, data models, logging, persistent connections, timeouts &amp; retries, and much more. All with an eye towards abstracting away complexity and reducing the amount of code a developer needs to write when integrating with your API.</p><p>The <a href="https://sdks.io/docs/category/support">support section</a> focuses on ways to support developers through different documentation formats. We look at the pros and cons of open sourcing your code libraries and how to support your SDK users in online forums and through traditional support teams.</p><h3>Ways to Build</h3><p>We are advocates of code generation and do a deep dive into <a href="https://sdks.io/docs/ways-to-build-sdks/code-generation/">OpenAPI generator and APIMatic </a>to show developers how to evaluate these types of solutions. We do our best to examine the tradeoffs between <a href="https://sdks.io/docs/ways-to-build-sdks/code-generation/build-vs-buy">building vs. buying</a> a code generation solution. Of course, <a href="https://sdks.io/docs/ways-to-build-sdks/homegrown">homegrown</a> SDKs may be the best way to serve your developer community, and we expect the best practices can help teams who take this approach. We also touch on ways to engage with developers who’ve built their own code libraries and made them available to your community.</p><h3>SDK Research</h3><p>Lastly, we’ve kicked off <a href="https://sdks.io/docs/industry-sdk-research">SDK industry research</a> to better understand the SDK programs of leading technology companies. By observing trends and sharing insights we can understand the state of SDK development.</p><p>You’ll definitely want to watch this space for interesting insights. For example, we discovered a vast array of programming languages are supported by companies. 18 languages were represented in our SDK survey with JavaScript/TypeScript being the most popular, followed by Python, Java, and Ruby. PHP barely edged out C# for 5th place. A signal of the shifting landscape, Go makes a strong showing in our programming language list along with Swift and Kotlin.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*zTVHSnt11V03oVmi.png" /></figure><h3>Why did we create SDKs.io</h3><p>Knowledge about SDK development is out there but tends to be scattered across blog posts written by teams who’ve built SDKs and are not intended to be a guide or a gathering place for the community of SDK builders.</p><p>Our aim is to provide a space where builders can share their triumphs and failures on the road to providing a better developer experience. There is no guide to building SDKs and you have to start somewhere, so we started with our experiences and learnings in the space.</p><p>This is an ongoing project and will get better over time. We don’t have all the answers and invite others to contribute their stories and experiences building SDKs. We’ve turned on <a href="https://github.com/apimatic/apimatic-sdks-io/discussions">GitHub discussions</a> as a place for conversation with us and each other.</p><p>We are human, so if you find an error and can <a href="https://github.com/apimatic/apimatic-sdks-io/issues">submit an issue</a> or a pull request, we’d really appreciate your help.</p><h3>What’s next for SDKs.io</h3><p>We’ve just launched, so feedback from the community would help us understand what you’re finding helpful and how we can improve. Our blog area will serve as a place for guest writers and SDKs news and updates.</p><p>SDK research is an area we are very excited about. This research is based on public SDK repositories and developer portals. Ideally, we’d like SDK builders to contribute information about their programs to increase the representation, accuracy, and richness of our data set. Also, what questions would you like answered about SDK trends. We’d love to hear from you and find ways to provide even more valuable insights.</p><h3>Who is APIMatic</h3><p>APIMatic builds SDKs and <a href="https://www.apimatic.io/developer-experience-portal/">documentation</a> for leading technology companies to enhance their developer experience and drive API adoption. SDKs built with APIMatic have been used by millions of developers.</p><p>APIMatic <a href="https://www.apimatic.io/continuous-code-generation/">auto-generates SDKs</a> and idiomatic code samples, which developers can copy and paste directly into their codebase. We also generate language-specific documentation, API reference docs, and how-to guides.</p><p>The platform includes an API Code Playground that allows developers to make API calls directly from the documentation and modify code in their preferred language to test the results.</p><p>Moreover, companies can choose to have documentation hosted by APIMatic, embedded in an existing developer portal, or deployed on their own domain. Updates to the developer experience are automated through full CI/CD integration.</p><p>If you’re a developer who wants to learn more about SDKs, you should <a href="https://sdks.io/docs/introduction/">check out the sdks.io website</a>. With its clear and concise explanations and practical examples, sdks.io aims to help you become a more efficient and effective developer.</p><p><em>Originally published at </em><a href="https://www.apimatic.io/blog/2023/04/say-hello-to-sdks-io-a-resource-for-sdk-builders/"><em>https://www.apimatic.io</em></a><em> on April 6, 2023.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f0a339669f6" width="1" height="1" alt=""><hr><p><a href="https://medium.com/apimatic/sdks-io-a-place-for-sdk-builders-f0a339669f6">sdks.io — a place for SDK builders</a> was originally published in <a href="https://medium.com/apimatic">APIMATIC</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>