November 2024 Summaries

Partner APIs are more prevalent than public-facing ones, yet often suffer from poor documentation, which significantly hampers integration efforts. According to the 2024 State of the API Report, nearly 40% of developers cite inconsistent documentation as a major challenge, leading to errors, miscommunications, and delays. A documentation-first approach, grounded in API specifications and managed through a git-based environment, can address these issues by providing a consistent source of truth, aligning with modern DevOps practices like CI/CD, and reducing integration friction. This method ensures that all API collaborators are on the same page, thereby enhancing partner relationships and improving the overall developer experience, which is crucial for revenue growth. The shift-left strategy involves creating and documenting specifications prior to development, promoting predictability and reducing errors, and is supported by tools like OpenAPI, which help standardize API behaviors. Ultimately, well-documented APIs, such as those from successful companies like Airbnb and eBay, drive significant business value by improving partner experiences, reducing customer churn, and increasing revenue potential.

Integrating user feedback into API documentation is crucial for enhancing user experience, and Bump.sh facilitates this by allowing feedback forms to be embedded directly through the x-feedbackLink extension in OpenAPI documentation. The process involves creating a feedback form using tools like Google Forms, Typeform, or Notion, and embedding the form link into the API documentation. Users can then provide feedback directly from the documentation, aiding in the continuous improvement of the API. Additionally, GitHub Issue Templates can be used as an alternative method for collecting feedback. This approach emphasizes the importance of keeping feedback forms concise and focusing on key questions to ensure higher response rates, while also encouraging regular review of feedback to promptly address user concerns.

BigID, a data intelligence platform, faced challenges with its API documentation process due to a surge in API demand and outdated systems that led to confusion and inefficiency. Developers had been manually sharing YAML files with technical writers, causing lost updates and redundant work, while the homegrown API documentation site lacked essential features. To address these issues, BigID transitioned to Bump.sh, which allowed for a streamlined docs-as-code approach where YAML files are managed in GitLab, reducing confusion and improving collaboration between engineering and writing teams. This change led to a significant increase in satisfaction among BigID's sales, support, product, and engineering teams, with notable improvements in documentation usability and efficiency. The automated changelog feature and enhanced user access management added to the platform's success, with internal feedback highlighting the improved experience and functionality. Bump.sh's integration and support have been pivotal, enabling BigID to replace old workarounds with scalable solutions, aligning with its rapid growth from a small startup to a company of over 500 employees.

OpenAPI v3.x introduces the discriminator field, often used with oneOf, anyOf, or allOf to handle polymorphism by indicating which schema to apply based on certain field values. However, its practical utility is questioned, as JSON Schema can manage similar tasks without this OpenAPI-specific feature. The discriminator acts merely as a hint for tools like code generators to quickly determine the relevant schema but does not contribute to validation, documentation, or other functions. The text argues that OpenAPI's oneOf and anyOf keywords, alongside schema properties like const, are sufficient for managing schema selection and validation without relying on discriminator, which is seen as an outdated concept. Modern tools and practices favor a more straightforward approach that leverages the natural structure of data and the flexibility of JSON Schema to provide meaningful validation and documentation without the need for discriminator fields.