April 2024 Summaries

JSONPath is a query language used to extract data from JSON documents. It has gained relevance with more tools and standards relying on it, such as OpenAPI. JSONPath allows filtering, querying, and traversing through complex JSON structures, making it useful for tasks like writing advanced linting rules or overlays in API documentation. The syntax of JSONPath includes elements like $ (root node identifier), @ (current node identifier), [<selectors>] (child segment), .name (shorthand for ['name']), and ?<logical-expr> (filter selector). By combining these elements, users can create powerful queries to manipulate JSON data. JSONPath is also used in tools like Bump.sh CLI for tasks such as updating or removing specific parts of an OpenAPI document.

Documenting APIs with OpenAPI is crucial for successful integration and adoption by developers. While reference documentation is important, other types of documentation such as code examples, getting started guides, and change logs enhance the developer experience. These elements together form a robust user interface for developers, facilitating easier API consumption and increased value for API consumers.

OpenAPI v4.0, also known as "Project Moonwalk", is set to be released in 2024 with a focus on making the next version of OpenAPI more approachable and less complex for both humans and computers to write and understand. The new structure aims to reduce nested structures to improve readability and editability. It will support APIs that have different responses based on query parameters, headers, and request bodies, as well as a broader range of URL design patterns by adopting the URI Template RFC. Ongoing discussions include replacing $ref with "imports", improving tags, removing discriminator, and enhancing links functionality.

The Bump.sh team has been working on adding features to their hosted service and command-line tools, while simultaneously providing guides for generating OpenAPI contracts in PHP. These guides cover both code-first and design-first approaches, with the main goal being to create an OpenAPI document that can be used for documentation and accelerating API development. The guides also provide examples of using Swagger-PHP to generate OpenAPI docs from existing APIs, as well as how to use packages like membrane/laravel and hotmeteor/spectator for validation and contract testing. Overall, the focus is on leveraging OpenAPI to prevent technical debt accumulation and improve API development efficiency.