March 2017 Summaries

Swagger 2 has transitioned to become OpenAPI Specification under the Linux Foundation, and the new OpenAPI 3.0 version introduces several updates and improvements over its predecessor. These changes include adopting Semver for versioning, replacing Github Flavored Markdown with CommonMark, and expanding support for JSON Schema features. OpenAPI 3.0 allows more flexibility in defining URLs, introduces path templating, and enhances the clarity of JSON References. Furthermore, it refines the structure of components, such as headers and requestBodies, which can now incorporate examples and support different media types. The response format benefits from wildcard response codes and the introduction of callbacks for webhooks. A significant addition is the linking feature, which provides a way to navigate between API resources, similar to hypermedia APIs. Security has also been updated, with new names and support for multiple OAuth2 flows and OpenID Connect. Although upgrading from Swagger 2.0 to OpenAPI 3.0 is lossless, the OpenAPI 3.0 specifications are not backward compatible with tools that only support Swagger 2. The final specification is yet to be released, but OpenAPI 3.0 is considered feature complete, offering solutions to many limitations encountered with Swagger 2.

Swagger, now under the Open API Initiative (OAI) after its transfer to The Linux Foundation, has evolved significantly over the past year, transitioning from a beta feature to a central component for API description. Swagger allows for machine and human-readable documentation of RESTful APIs, facilitating both design and documentation processes. To generate a Swagger file, one can utilize various methods, including the official Swagger Editor or custom build tools, but Swagger Inline offers a streamlined approach by enabling API documentation directly within code comments, which can then be published with a single command. The process begins by installing the OAI tool, guiding users through the creation of a Swagger file, while the ReadMe platform supports integration with Swagger to enhance API development.

Planning a successful conference involves overcoming initial overwhelm and making the idea tangible by focusing on practical steps such as estimating costs, reaching out to experienced planners, and committing to concrete actions like booking venues and confirming speakers. The journey from concept to execution requires a clear understanding of the event's purpose, ensuring it offers genuine value beyond mere brand exposure, and aligning it with the interests of the organizers and potential attendees. This process, as experienced by the team at ReadMe, emphasizes the importance of focusing on the core audience and purpose, in their case, creating a conference centered on API developers to build and strengthen their community.

Node.js v7.6.0 introduced a significant update to its underlying JavaScript engine, v8 5.5, incorporating native support for async functions, which enhances the readability of promise-based code by allowing developers to use the async and await keywords. This update makes asynchronous code appear more synchronous, reducing complexity and improving error handling by using try...catch blocks instead of chaining .catch methods to each promise. The inclusion of async functions in the language removes the need for transpilers like Babel, promoting wider adoption and cleaner code. However, developers need to be cautious as excessive use of async/await can lead to performance issues and may indicate deeper architectural problems. In non-promise-aware environments like Express, helper functions can be used to unify error handling and streamline code structure. While async/await greatly simplifies code, developers should remain vigilant about potential performance pitfalls and maintain thoughtful architecture to avoid unintentional slowdowns.

A recent change to a 14-day trial prompted the need for synchronized welcome campaign emails, which were implemented using Customer.io's triggered campaigns. The email campaign, inspired by Squarespace's model, consists of four emails sent throughout the trial period to establish communication, guide users towards key features, and remind them of the trial's expiration. The emails are personalized using liquid tags and are sent based on user activity tracked by a cron job, ensuring timely delivery aligned with each user's trial progress. While the effectiveness of these campaigns is still being evaluated, there has been an observed increase in upgrades, and future plans involve exploring more targeted drip-campaigns and Customer.io's "newsletter" format for non-triggered emails.