Jul 22

APIAddicts Joins OpenAPI Initiative

By Open API Initiative Announcement, Blog

Welcome to APIAddicts! APIAddicts boasts one of the largest communities of API practitioners with an extensive international presence in Spanish-speaking countries including Spain, Perú and México with 5,000+ APIAddicts worldwide, and over a million visualizations.

APIAddicts hosts multiple events throughout the year for developers wanting to discuss, learn more, and contribute to the growth and integration of APIs. Many details are provided in the interview below. APIAddicts Days is one of the most important events hosted by them annually. Companies and professionals share their experiences while analyzing the successes and failures in the current framework that supports API. To find out how APIAddicts Days was in 2020, click here.

APIAddicts has a strong education focus. Their School of API’s aims at helping professionals improve their use of APIs. At the end of the courses, you are awarded an API Evangelist Certificate / Recognition / Diploma.

We wanted to learn more about their upcoming events and the latest updates in the API world, and what working with the OpenAPI Initiative would look like. We talked to Marco Antonio Sanz, founder of APIAddicts, to find out more!

How was APIAddicts born?

In 2013 five very techie friends and colleagues were working in large companies managing APIs and realized a lack of APIs documentation and education in Spanish at that moment.

So they started giving a series of informal talks to share their knowledge. Meetup groups were created, which are still active today, to connect with other people interested in digital transformation and we started to meet monthly to talk about news or updates in the sector, actually the first meetings were in a bar in Getafe, until it was gradually formalized.

This was growing and finally formed what today is APIAddicts, the largest Spanish-speaking community around APIs with more than 5,000 APIAddicts in Spain, Chile, Peru, Mexico, Colombia and Argentina.

How hard is it to get an API Evangelist Diploma? What are the main benefits?

The evangelization of APIs and the training of professionals in it is so important, so from the Foundation we wanted to go a step further and help companies to qualify their teams with the most updated knowledge and from the best experts.

We had already been doing the API Owner course for years, which is in great popular demand today, and we decided to complete the training with the specialization courses in Security, Testing, Design and Architecture. This way you can get an overview of the entire APIfication process of a company and learn how to manage each of these phases optimally.

All the courses involve a total training of 50 hours with 80% of hands-on practice where students can apply the knowledge they have learned. Once the courses are finished, they present an API project to the teachers, who evaluate and assess the documentation.

If they achieve the API project taking into account the requirements and concepts of the courses, they obtain the certifications of each specialty and the API Evangelist Diploma, the highest certification for an API professional.

Nowadays there are many companies that trust in the courses of the API School of the Foundation and with them they specialize their teams, PM, QA, Technical Lead, Analysts, Coordinators… Taking these courses guarantees you knowledge in the whole APIfication process and a clear management of the necessary tools. This not only increases your job projection but also your career within the companies.

What is APIAddicts mission in the evangelization of APIs?

We have always been aware that, although APIs are a key factor in companies that want to be competitive today, it is a term that generates a lot of confusion. Therefore, we could say that the APIAddicts Foundation’s evangelizing mission began in 2013 when APIs were already being used but no one fully understood what they were for. In fact, the role of our community has been essential to introduce the transformative potential of APIs in Spain.

In this sense, we carry out annual studies, Open Source tools, training courses, 3 large events: Webseries, Startups and APIs and APIAddicts Days and more than 20 annual meetups. We are the community that has created more API documentation in Spanish and now we hope to continue doing so with OpenAPI.

We believe that if we had to define what our main differentiation is, it would be that we always try to have the best referents of the sector to inspire in the use of APIs and always from a close treatment, being a real community. That is why, for example, all our API School courses are not recorded because for us this makes you lose an essential part of the API training: sharing experiences and real cases with the live expert.

Finally, every day, and more and more strongly, we continue to do what we were born for: to bring the knowledge of APIs to every Spanish-speaking corner of the world, in a disruptive way.

What is the relationship between APIAddicts and CloudAPPI?

After starting the evangelization of APIs through talks and meetups, the community was gaining popularity and with it came business opportunities. This became a turning point in which they decided to leave their usual jobs to set up their own consulting firm, outside the bases of the association, because on one side runs the foundation and on the other the company, but they could accompany each other as partners in their growth, both approaching the life cycle of the APIs from different points of view.

Therefore, today the relationship between both entities is based on sponsorship, so they actively participate in different events. However, the Foundation supports itself with its own budget thanks to the other sponsors, courses of the API School and prices of some of the tickets for our events.

We always had it clear, the Foundation was born altruistically by a group of teckie friends who love APIs to promote the knowledge of APIs in Spanish and will always remain so.

Why did APIAddicts join OpenAPI Initiative and why now?

In these last few years we have been trying to take API Evangelism further in all formats: Open Source tools, international events, new broadcasting formats such as podcasts, specialization courses… Within all of this, we saw the need to be part of a development community as essential for the future of APIs as the OpenAPI Initiative.

This way we can offer added value to our community and increase the role of the Foundation in the future of APIs. We want to help to improve the specification and thus improve the level of the tools that allow the implementation of API First methodologies, such as API Tools.

We enjoyed hearing from the APIAddicts team and learning about the fantastic work they are doing. We appreciate the value they place in community building and vocalizing the needs of the API community.

OpenAPI Resources

To learn more about participate in the evolution of the OpenAPI Specification: https://www.openapis.org/participate/how-to-contribute

About the OpenAPI Initiative

The OpenAPI Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how APIs are described. As an open governance structure under the Linux Foundation, the OAI is focused on creating, evolving and promoting a vendor neutral description format. The OpenAPI Specification was originally based on the Swagger Specification, donated by SmartBear Software. To get involved with the OpenAPI Initiative, please visit https://www.openapis.org

About Linux Foundation

Founded in 2000, the Linux Foundation is supported by more than 1,000 members and is the world’s leading home for collaboration on open source software, open standards, open data, and open hardware. Linux Foundation projects like Linux, Kubernetes, Node.js and more are considered critical to the development of the world’s most important infrastructure. Its development methodology leverages established best practices and addresses the needs of contributors, users and solution providers to create sustainable models for open collaboration. For more information, please visit us at linuxfoundation.org.

Jul 21

Love0

OAI Additional Leadership Job Posting

By Andrew Bringaze Announcement, Blog

The OpenAPI Initiative (OAI) is looking for three individuals to fill three separate year-long contracts to help lead the conversation around the leading API specification. We are looking for three self-starting individuals who are familiar with the OpenAPI Specification (OAS), and will help roll up their sleeves and help move a handful of projects forward.

The OpenAPI Specification (OAS) has emerged as the leading way to describe the surface area of your APIs in the last five years, and the need for help to support the community has grown dramatically. As part of this growth we’ve identified a few priority projects we are managing using Github Projects, and would love to get you involved!

Projects

Here is a list of the current projects OAI members and community have prioritized, which we have also tagged by the type of work involved, shared a brief description of what is involved, and provided a link to the Kanban board for each project.

OpenAPI Search Engine Optimization (Marketing) – Ongoing work to help improve the search engine optimization for the OAI and OAS, helping elevate the presence of the specification.
New Member Identification & Engagement (Marketing, Community, Business Development) – Work to identify potential new members to the OAI and reach out to them to help start a conversation and make them aware of the benefits of being a member.
Member Showcase & Engagement (Marketing, Community, Business Development) – Continually improving how we showcase and engage with the members of the OAI, and increase their participation within the OAS community.
Profile & Engage with API Providers (Community, Business Development) – Work to identify, profile, and build relationships with API providers who have implemented the OpenAPI specification, and publish profile to a central database.
Profile and Engage with Open Source Tooling (Marketing, Community, Business Development) – Establish an official directory of open source tooling that uses OAS, and actively work to establish and build relationships with each tooling provider to get them more involved in the community.
Curate and Publish API Articles, Podcasts, Videos (Marketing) – Work to discover, curate, and then showcase and syndicate the existing articles, podcasts, and videos that exist about OpenAPI.
Business Sector Showcase & Engagement (Business Development) – Work to profile business sectors that are putting OpenAPI to work, then engage, and build relationships with individuals or organizations, while helping stimulate OAI special interest groups in these areas.

All of these positions require leadership qualities to help define, prioritize, and execute on plans, and to engage with the OpenAPI community to increase participation, member value, and drive overall community energy.pods

Contract Details

These are the details of the work, with more details available upon request:

3 Individual Part-Time Contractors
One Year Contract from September 15th 2021 through Sept 15th, 2022)
Open to Global & Remote Contract Works
Fixed Price Contracts ($2,500.00 Monthly / $30,000.00 Annual)
Monthly Report Demonstrating the Value of Work

Requirements

These are the basic requirements for being considered for the contract positions:

OpenAPI Awareness
Project Management Skills
Writing and Editing Skills
Enjoys Working with People
Embraces values of collaboration, inclusion, and diversity

Contract Pitch

When applying for one of the contracts, please pitch us on which project or projects your skills are a match for accomplishing, and demonstrate why you would be our choice to help not just make a project happen, but help us lead where the project goes next.

How to Apply

Please email your cover letter, resume, and any questions to jobs@openapis.org by August 15th, 2021 to be considered for the positions by the OAI hiring committee, with a start date of September 15th, 2021.

Get Involved

Even if you aren’t interested in submitting for any of these job postings we encourage you to get involved in the community and help out on any of these projects. In addition to participating as part of the weekly technical and marketing meetings, the OAI is looking for help across these projects, writing blog posts, and creation of educational materials, so please feel free to reach out via social channels or email to get involved.

Jul 15

Love0

An OpenAPI Interview with Marc-André Giroux of Github

By kinlane Blog

By Kin Lane, Chief Evangelist at Postman, and Co-Chair of the OpenAPI Initiative (OAI) Business Governance Board (BGB)

I recently sat down with Marc-André Giroux, Staff Developer at GitHub about their OpenAPI journey, to learn more about how the social coding platform employs OpenAPI across the API lifecycle. GitHub plays a central role in the development of software of any kind and is also central to the entire API lifecycle, but the platform’s APIs provide a wealth of learnings when it comes to how to deliver API infrastructure scale. So we are honored to have sat down for this discussion about the OpenAPI journey GitHub is on, and share this vision with the OAS community.

When did you begin your journey using the OpenAPI specification?

GitHub began looking into OpenAPI in 2019. Funnily enough, two teams started to look at it independently, which highlights how OpenAPI brings many different benefits to the table. On one end, our documentation team wanted a machine-readable document from which to generate their documentation. On the other hand, the API team (the team I am on) wanted to use OpenAPI as something core to our API development experience. Things like having a design-first flow, request validation, contract testing, linting, etc.

Our documentation team started exploring with OpenAPI first. They ingeniously generated an initial document from our hand-written documentation. This was a great start, but from our API team’s perspective, since it was generated from something that we could not entirely trust, it was important for us that this OpenAPI description was being tested against, and used by our runtime code to make sure it is both accurate and complete.

Over the first half of 2020, we worked with the documentation team to use their initial work, bring it over to the API’s codebase and use it in a validation middleware that would tell us about any mismatches. We built tooling to automatically fix errors, fixed a lot of errors by hand, and in July 2020, we were ready enough to release the beta of our OpenAPI description.

What teams are currently using OpenAPI within your organization?

The surface area of our API is very wide. Almost every team working on a feature at GitHub will end up writing an API for it. This means that in the end, a ton of different teams interact with OpenAPI. As the API team, we consider these teams to be our customers as well. We make sure their experience with OpenAPI is great and that we have the right tooling to help them build great APIs. Our documentation team also uses OpenAPI to generate most of our API documentation website.

Is OpenAPI used for public APIs? Internal APIs? Or Both?

OpenAPI is currently only used for our public API. We have a lot of internal APIs that we would eventually like to describe with OpenAPI. However, we’ve recently made the switch to using Twirp for most internal use cases, which is described by Protobufs.

Can you share more about how OpenAPI is being used across different areas?

Documentation:

The OpenAPI written by our developers gets automatically synced with our documentation repository. Our documentation team built an amazing pipeline which decorates the OpenAPI further and is used to render our API documentation.

Code Generation

We also sync the OpenAPI description in our open-source repository. This is used by our first use case of code generation, the Octokit JS SDK. Gregor Martynus did an amazing job using the OpenAPI we publish to generate typescript types and power the javascript SDK.

Soon, we want to help our own developers with code generation as well. We already leverage OpenAPI operations at runtime to configure certain resources, but we want to push it further and help generate implementations from OpenAPI operations.

Testing

GitHub’s API is implemented in an enormous Ruby monolith, with thousands and thousands of existing tests. We leveraged this by including a custom OpenAPI validation middleware in our existing integration testing suite for the API. This contract testing is integral to our confidence in the accuracy of our OpenAPI documents and was one of the hardest, and most important, parts of our OpenAPI work.

A lot of existing OpenAPI validators return errors that are not necessarily friendly to users. We spent a lot of time coming up with an abstraction that lets us return errors that are either developer-facing or end-user-facing. For example, the OpenAPI validation errors that are returned as part of our integration tests return error messages that instruct the developer on why the error happened and how to fix it. On the request validation side of things, we instead instruct the user on why their input was invalid, and how to correct it.

What were the driving factors for you to adopt OpenAPI?

While generating documentation was an amazing benefit, OpenAPI was more than just that to us. Enabling powerful tooling and building a great developer experience were the main reasons we looked at OpenAPI.

Do you make a copy of your OpenAPI available for download by users? If so, where do you make it available?

We do! As mentioned earlier, we have it available as an open-source repository located here.

Do you currently have any OpenAPI extensions you are using or have established as part of your operations?

We use quite a few extensions that are useful at different stages of the “lifecycle” of our operations. We support many different versions of GitHub’s REST API. Our classic public API, but also every version of GitHub enterprise. While the APIs are similar, they do have differences across versions. Instead of duplicating every single operation and components, we opted for a build system that would allow us to annotate OpenAPI objects with versioning information. For example we have a `x-github-releases` extension that allows developers to include or exclude operations from certain releases. This extension is not present in our published descriptions since it is stripped by that build system.

We have other public extensions that add some GitHub-specific metadata to some OpenAPI objects. For example, we have an extension called `x-github-previews` which informs whether this operation is part of an API preview.

Other extensions are described in our open-source repository.

Is your team joining the technical developer community conversations to evolve the OpenAPI specification?

Not at the moment, but the recent overlay specification talks are of great interest to us. We will most likely join these conversations very soon.

Do you use other API specifications (ie. AsyncAPI, GraphQL, gRPC)? If so, can you share details of why?

We do! We use GraphQL as another public API which offers a different experience to GitHub’s domain and more flexible use-cases to our customers (more about this here). As mentioned earlier, we also use Protobuf for our internal Twirp APIs.

How did you convince leadership in your organization that OpenAPI was an important investment?

Fortunately, leadership was already onboard with using a machine-readable document to describe our APIs. We had extensive usage of JSON hyper-schema already, but the fast adoption of OpenAPI in the community and how it would allow us to describe our APIs accurately made us choose OpenAPI in the end.

In Conclusion

GitHub’s adoption of OpenAPI follows similar trends we are seeing with other leading API providers like Salesforce, Twitter, Plaid, and others. Multiple teams are realizing the benefits of using OpenAPI, with documentation being the number one driver, but then code generation and testing being second and third. API providers who are further along in their journey have realized that OAS doesn’t always do 100% of what they need and, like GitHub, are extending the specification and increasingly moving towards participation in the weekly technical developer community calls to help evolve the specification. It is gratifying to see leading providers like Github recognize and start to leverage the benefits of the OpenAPI Specification (OAS) for their business, and we look forward to having them more involved in the community.
If you’d like to share your OpenAPI journey story we’d love to hear from you. While many of the details between Plaid, GitHub, and other API provider stories are similar, it helps to tell stories from multiple perspectives and business sectors. If you have an OpenAPI story you’d like to share, feel free to submit a GitHub issue with your ideas, and we’ll consider adding it to the editorial queue. We wanted to thank GitHub, and Marc-André Giroux for letting us interview them, and share this great story with the OpenAPI community. Thanks to GitHub for providing us all with another example of why GitHub is a leader when it comes to how technology is delivered in the 21st century.

Jun 16

Love0

OpenAPI Initiative Welcomes RapidAPI

By OpenAPI Initiative Announcement, Blog

RapidAPI is joining the OpenAPI Initiative! RapidAPI helps developers find, manage, and test APIs. They provide an API Marketplace for developers to discover and connect to thousands of public APIs. The company’s services can be tailored to a company’s brand, to build private marketplaces for internal and external APIs. Notable enterprise clients include SAP, Cisco, Tata, and Hyatt.

To learn more about RapidAPI Marketplace, sign up for a free account here.

To better understand how RapidAPI provides a next-generation infrastructure for APIs and what a collaboration with the OpenAPI Initiative would mean for them, we asked Iddo Gino, CEO and Founder.

Why did RapidAPI join the OpenAPI Initiative, and why now?

APIs are the heart and soul of RapidAPI. With acquisitions like the Paw Client and unique developer tools such as RapidAPI Testing — we care deeply about the developer experience of writing, publishing, and ultimately maintaining APIs. OpenAPI plays a significant role in all of this.

Our goal in joining the OpenAPI Initiative is to give back to the community. As we build the next-generation of API Developer Tooling, it’s more important than ever to be part of the API builders’ community conversations. OAI is where API builders and API consumers go beyond the original spec to collaborate on exciting things such as JSON Schema and Asynchronous APIs and beyond. RapidAPI wants to help advance the specification through participation in the community.

Additionally, we’re committed to making our platform easily interface with 3rd party tools. Therefore, it’s important for us to continually support the OpenAPI Specification format, allow interconnectivity of all tools, and avoid customer lock-in.

The RapidAPI team has a history of participation in development communities. Our Head of DevRel Ahmad Awais is an active voting member of the Node.js Community Committee and WordPress Foundation Core Contributor before that. Our Head of Marketing, Suzanne Panoplos, has been active in the Open Container Initiative and CNCF. As you can see, joining the OpenAPI Initiative and becoming a member of the Linux Foundation couldn’t be a more natural transition for RapidAPI.

What goes into making an API marketplace? What makes one better than the other?

A robust API marketplace enables developers to find, connect and manage APIs from a single place and support a variety of APIs including REST, SOAP, GraphQL or Asynchronous APIs. For each API you should be able to see performance metrics like average latency, uptime, and popularity and be able to test the API from the browser.

Additionally, a marketplace should enable you to:

Gather information about each API using the endpoints page to view a list of endpoints, documentation, and a code snippet to help you implement the code into your app.
Subscribe to API plans to start using it. Manage all your API subscriptions and payments through a single source.
Utilize a single key for all your APIs.
Manage applications and API keys using a single dashboard. Using this dashboard, you should be able to:
- Monitor API performance by visualizing how many requests are made to different APIs, tracking the number of requests that return an error, and viewing latency data for each API.
- Debug faster by inspecting the logs for all requested data.
- View usage and billing information for a breakdown of API spending, including the monthly recurring and overage charges.
- Manage subscriptions from one place including quota usage and time remaining until the quota limit resets.

How has COVID affected the use of APIs in the past year?

With the pandemic, digitalization has gone from being a “nice to have” to an imperative to survival. Take Starbucks as an example. Before the pandemic, 7% of Starbucks revenue came from mobile ordering. During the pandemic, 100% of their revenue came from mobile ordering as most stores were closed to in-person ordering.

To react to the changing environment during the pandemic, companies had to adjust their application development process and accelerate their delivery to address changing market conditions. To do so, companies have to rely on APIs in their software development.

This trend is true across almost all industries during the pandemic. Still, there has been an explosion of API usage in healthcare settings, where services, appointments, and scheduling have taken place online to the homebound consumption of services such as food ordering, retail, etc.

This trend was highlighted in RapidAPI’s 2020 Developer Survey, released earlier this year. The survey indicated that developer reliance on APIs accelerated during the pandemic and will continue to increase in 2021.The data revealed that 61% of developers used more APIs in 2020 than in 2019, and 71% plan to use even more during the upcoming year.

What’s your vision for API marketplaces 1-3 years out?

As API proliferation continues to increase across all organizations, enterprises will find it to be a necessity for finding, connecting to and managing their APIs. Marketplaces will need to provide:

An Open Platform – With organizations using disparate API gateways, marketplaces will offer a platform for integrating with multiple different gateways and clouds.
Developer Experience – Marketplaces will need to be continually developer-first, providing the key features needed to deliver API use and reuse such as deep search and tagging API analytics for providers or consumers, and advanced usage controls for developers.
Out of the box experience – Marketplaces will need to have everything developers need to succeed including advanced features such deep search, end user analytics, and developer registration workflows.
Many-to-Many Model – Marketplaces will need to support multiple teams of API providers offering APIs to internal consumers as well as partners and customers.
Support for All API Types – Marketplaces should support all of the last APIs including SOAP, REST, GraphQL, Async APIs like Kafka, and more.
Scalability – Marketplaces should scale to support hundreds of APIs with room for future growth.
Governance – Marketplaces will unify visibility and governance across all APIs in the organization, regardless of which clouds or API gateways are in use.

We are excited to welcome RapidAPI to our list of growing members and look forward to working closely together!

OpenAPI Resources

To learn more about participate in the evolution of the OpenAPI Specification: https://www.openapis.org/participate/how-to-contribute

About the OpenAPI Initiative

About Linux Foundation

May 20

Love0

Announcing the API Specifications Conference (ASC) Early Bird Submission Deadline

By Andrew Bringaze Blog

The third API Specifications Conference (ASC) will take place on September 28th and 29th. This year as part of the call for proposals we’re going to be accepting and announcing five talks early. In order to have your talk considered, you need to have your submission in by May 28th, 11:59pm PDT.

The early bird submission will give you advance notice to prepare for your talk and your talk will be announced before the full schedule is announced.

Submit your talk at: https://sessionize.com/api-specifications-conference-2021/

Early bird deadline: May 28th, 11:59pm PDT

Regular deadline: June 11, 11:59pm PDT

We will notify any speakers who have an early bird submission accepted within two weeks after the deadline.

If you need help or advice for your submissions, please contact speakers@openapis.org. If you are a first-time and/or underrepresented speaker, we especially want to help you submit a talk and are available to help you work through talk ideas or how to structure your proposal.

On behalf of the organizing committee,

Taylor Barnett, Program Chair, ASC 2021

Apr 27

Love0

Checkly, API Monitoring and Automation, Joins OpenAPI Initiative

By OpenAPI Initiative Announcement, Blog

Customer base already heavily utilizing OpenAPI Specification, Checkly “doubling down” on open source with increased contributions to projects like Headless Recorder and monitoring-as-code

SAN FRANCISCO – April 27, 2021 – The OpenAPI Initiative, the consortium of forward-looking industry experts focused on creating, evolving and promoting the OpenAPI Specification (OAS), a vendor-neutral, open description format for RESTful APIs, is announcing today that Checkly has joined as a new member.

Checkly provides a monitoring and testing platform for developers and modern DevOps teams. The Berlin-based company’s cloud platform allows developers to monitor their API endpoints and web apps. Customers can configure fully-fledged HTTP requests with flexible assertions and setup/teardown scripts. To monitor web apps, Checkly runs JavaScript and open-source powered browser checks.The company has also developed the open source Headless Recorder for creating end-to-end testing scripts through a Chrome extension. As a critical initiative, Checkly’s focus is on monitoring-as-code enabled through its public API.

“We are very excited to join the OpenAPI Initiative. Our customers and we are benefitting from standardized APIs. OpenAPI enables our customers to get their API monitoring setup started easily and therefore provides immense benefits in flexibility and openness,” said Hannes Lenke, CEO at Checkly. “We see the opportunity to contribute to the initiative through our day-to-day experiences and want to connect with key players in the field to discuss ideas and network. In 2021 we want to double down on OSS and as part of the initiative joined OpenAPI as we see as a great and natural fit.”

“With the growth of DevOps and microservices, API usage has skyrocketed. Monitoring and testing is key in modern production environments, and OpenAPI documents can really help with the authoring process,” said Marsh Gardiner, Product Manager, Google, and Technical Steering Committee, OpenAPI Initiative. “We look forward to Checkly’s support of the OpenAPI Specification moving forward.”

Checkly raised a $2.25 million seed round led by Accel. Angel investors Instana CEO Mirko Novakovic, Zeit CEO Guillermo Rauch and former Twilio CTO Ott Kaukver, also participated in early funding. For more information, please visit https://www.checklyhq.com/. To learn how to learn how to simplify API monitoring with OpenAPI specs and Checkly visit: https://www.checklyhq.com/guides/openapi-swagger/

OpenAPI Resources

To learn more about participate in the evolution of the OpenAPI Specification: https://www.openapis.org/participate/how-to-contribute

About the OpenAPI Initiative

About Linux Foundation

Apr 15

Love0

ASC 2021 Call For Proposals!

By Andrew Bringaze Blog

After a successful virtual event last year, we are back again this fall. Mark your calendar for the return of the API Specifications Conference (ASC), this year as an all-digital event on September 28th and 29th, 9:00 am – 3:00 pm PDT.

ASC 2021 will include keynotes, sessions, and open discussions on specifications and standards behind the cutting-edge technologies that chart the future of APIs. And we want to hear your talk proposals!

We are looking for talks that range from beginner introductions to API specifications through best practices and forward-looking sessions on API specifications and standards, including OpenAPI Specification, gRPC, AsyncAPI, GraphQL, RAML, API Blueprint, oDATA, JSON Schema, and others. We want to hear your talks on how you are using specifications and standards in practice. Topics can include but are not limited to design, testing, security, lifecycle, runtime, governance, and developer experience. In-depth talks and discussions will enable attendees to get familiar with these specifications and standards and how to use them to deliver better API experiences.

Check out last year’s talks to get an idea of the different kinds of talks we have had in the past: https://www.youtube.com/playlist?list=PLcx_iGeB-Nxil4S7-0Y1Y5r0oLahy3f0Y

The Call for Talks is open:

* Submit your talk: https://sessionize.com/api-specifications-conference-2021/

* Submissions Deadline: June 11, 11:59pm PDT

We’re looking forward to your proposals and participation that will make ASC 2021 a great event again this year!

On behalf of the organizing committee,

Taylor Barnett, Program Chair, ASC 2021

Apr 13

Love0

Leveraging the OpenAPI Specification in Financial Services – The Story of Plaid’s OpenAPI Journey

By OpenAPI Initiative Blog

Written by Kin Lane, Chief Evangelist, Postman

The complexity of providing financial services to businesses and consumers in today’s business climate is hard to overstate. APIs are a critical component in providing products and services.

Plaid, whose mission is to democratize financial services through technology, is a company that provides APIs for developers building applications in the fintech space. Plaid’s platform allows applications to connect with users’ accounts at banks and other financial institutions. Consumers and businesses can take advantage of a wide array of Plaid-powered apps to quickly and easily transfer funds, analyze their spending, apply for loans, and more.

Based on the new OpenAPI Specification 3.1.0, Plaid built an API document which allows them to easily release updates to their client libraries (they support five: Ruby, Node, Python, Java, Go). And, they have released an OpenAPI file for auto-generating your own client libraries in your preferred programming language, making it simple for you to auto-generate your own client libraries in over 40 different languages–so you can easily build with Plaid no matter the language you use.

The Journey to OpenAPI

The OpenAPI journey at Plaid did not begin with a single person or team, but was something that grew out of multiple teams with different motivations for why they needed a single machine readable truth to exist for their banking APIs. I recently spoke with Alex Hoffer of the developer relations team at Plaid to learn more about the motivations behind why Plaid chose to use the OpenAPI Specification, but also understand a little about how they arrived where they are at.

Plaid had recently published their OpenAPI to a GitHub repository , and I thought it was a great opportunity to reach out and talk about their adoption of the OpenAPI Specification and see if they were willing to share their story with us. They were! So thank you to the Plaid team for talking with us, and sharing the details behind how OpenAPI is being applied across API operations at the banking API platform.

Creating Better Documentation More Quickly

Like most API providers, the number one reason Plaid adopted the OpenAPI Specification (OAS) was to deliver documentation for their public API. Plaid’s documentation had been in use for quite some time now, and needed a refresh, so the developer relations team embarked on a complete rewrite, and they wanted to make sure they were able to future proof their documentation so that they could evolve it alongside their API. After researching the situation it was clear that the OpenAPI Specification (OAS) was the most effective way for describing Plaid APIs in a way that would be extensible and allow it to power the current and future state of their banking API documentation. The Plaid team moved forward with a complete reworking of their documentation, and as they were working on delivering a complete OpenAPI for the Plaid API documentation other teams were also putting OpenAPI to work powering their own corner of the Plaid platform.

Delivering Client Libraries

As the developer relations team was working on the Plaid OpenAPI document, their developer experience team was also working understanding how it could also be used to deliver client libraries for the API across multiple programming languages. The developer experience team at Plaid pushes the release of multiple SDKs for the API every two weeks, which is a manual process that takes a significant amount of work and is prone to errors, while also requiring significant expertise in each language required to deliver the best possible SDK. With all this work the developer experience team was very keen on being able to automate as much of the process as possible, but as they got to work on generating SDKs from the OpenAPI they realized that the process would demand a much more robust and complete OpenAPI to deliver all of the details needed for each of the language libraries. Ultimately it took the team five months to deliver a beta set of SDKs that met the team’s expectations, but now they have a much more streamlined approach to delivering SDKs across multiple languages, while also ensuring that the SDK release process is always in alignment with the evolution of API documentation, since they both are driven from the same machine readable truth—the Plaid OpenAPI contract.

JSON Schema Now Available

Beyond developer relations and experience at Plaid, the core services team also caught wind of the OpenAPI that was being used to power documentation and generate client SDKs. The team was interested in the centralization of a machine readable truth for the Plaid API, but were particularly interested in the JSON schema now available to describe the request and response payload for each API. There was anxiety from internal developers when it came to introducing changes to the schema that was used to power the platform, and with limited visibility into what might be a breaking change with any release, developers were left with a lot of questions. With the existence of a central set of JSON Schema definitions now available as part of the OpenAPI, internal developers could now use them to validate as part of pipelines and middleware across the Plaid platform, ensuring that ongoing changes did not update or remove any properties that might introduce errors into the APIs and downstream applications of integrations. Leveraging the central OpenAPI to help make releases more reliable and less stressful for internal developers who were moving the API platform forward with new features and capabilities—reducing friction for the Plaid platform.

Defining Extensions

With the introduction of OpenAPI into the documentation, validation, and delivery of SDKs for the Plaid APIs, there were numerous immediate benefits that the teams were able to take advantage of. However, all three teams quickly began bumping against the limitations of what the OpenAPI Specification was capable of defining. Some of these needs were unique to the way Plaid does things, but other needs resemble many of the common needs you see across other API providers. This didn’t slow the Plaid teams down, and they quickly got to work defining extensions for OpenAPI that would help them define what they needed for documentation but also the very demanding needs of generating SDKs in multiple programming languages. Most notably, they also established an x-plaid- extension that would be used to describe internal schema and capabilities that would be stripped from the OpenAPI anytime the definition would be made available to the Plaid community. This work really helped Plaid realize that the OpenAPI specification really shines when you extend and push the specification to do exactly what you need, allowing the machine readable truth for their API to effectively deliver multiple essential stops along the API lifecycle like documentation, SDK generation, and validation.

Customers Request OpenAPI Specification

The Plaid OpenAPI journey reflects what many OpenAPI adopters have experienced, or are currently experiencing. While there are many motivations for why API providers adopt OpenAPI, the need to power always up to date API documentation and SDKs in a variety of programming languages are the top two. It is a journey that usually begins with the need for providing better documentation, but then as teams realize the same OpenAPI can be used to power other stops along the API lifecycle, they really see the potential of the API specification as a single source of truth or APIs. It is great to hear the story behind why Plaid is using OpenAPI, and hopefully this story provides a look into the “known knowns” of what OpenAPI can do within Plaid, but as I was finishing my conversation with Alex Hoffer, I asked her why they had published their OpenAPI to GitHub—which ultimately was the catalyst for this conversation. She simply said that an OpenAPI was a common request from their customers so they could generate their own libraries for languages they didn’t support, but also after speaking with other leading API Providers in the space, they had mentioned they were surprised by the unique things that their community was doing with their OpenAPI, innovating beyond what internal teams could deliver. Which really gets at the most powerful reasons for providing an OpenAPI for your API community, in that it will enable entirely new approaches to putting your APIs to work, which is really why we are all doing APIs in the first place. OpenAPI is just amplifying this effect and taking things to entirely new levels.

Mar 11

Love0

OpenAPI Initiative Welcomes Level 250 as Newest Member

By OpenAPI Initiative Announcement, Blog

Level 250 is joining the OpenAPI Initiative! Level 250 is a consulting organization that helps companies large and small improve their Product Strategies around SaaS, APIs and Developer-focused Tools: https://www.level250.com

Level 250 is run by Emmanuel Paraskakis, who has over 20 years of far-reaching experience in Product Management in organizations ranging from early-stage startups to Fortune 500 companies. Paraskakis was VP of Product Management for two of the most important API products in the world: Apiary with API Blueprint (acquired by Oracle) and SwaggerHub (and the Swagger Open Source toolset) which uses OpenAPI.

With that extensive API and product background, we asked Paraskakis about Level 250, implementing the new OpenAPI Specification 3.1.0, and where APIs are headed. We found out about how the requirements of API builders and API consumers are converging, about major improvements in reuse that will help managing scale, helping non-humans (yes), and a lot more!

— Why did Level 250 join OpenAPI Initiative and Why Now?

I have always been involved in OpenAPI, with two previous member companies, Apiary and SmartBear and so it’s part of my background. APIs and OpenAPI are at the center of everything we do at Level 250, so I want to continue to support OpenAPI in any way I can.

What makes this even more relevant today is that OpenAPI is becoming so much more that just one Spec: it’s the place where thinking and collaboration around APIs happens, whether it’s about the original OpenAPI spec, or adjacent specs such as JSON Schema and AsyncAPI, and beyond. I think OAI is becoming a focal point where the requirements of API builders and API consumers are converging. Exciting times!

— What’s the biggest issue with implementing the OpenAPI Specification?

I think the Spec is a wonderful interchange format, a Lingua Franca that most API Tools speak, so you can for example take a document that was meant as a design and reuse it to configure your API Management or your Security tests.

But because it’s become complex, encompassing many use cases, I think it’s difficult to learn and I also think it’s hard to write, for the Design-first use case for example. There are tools that make the process easier, with syntax suggestions or even UI editors, but the underlying complexity remains.

I’d love to see a simpler language that could be written by hand, perhaps leveraging examples, during the ideation and design process, and that could then translate directly into the current Spec for interoperability.

Beyond that, I think we could work more on making modularity and composition easier and also the handling of metadata, discovery and runtime configuration of API Gateways.

— Who should use the OpenAPI Specification 3.1.0?

I think the most exciting news is the full JSON Schema compatibility and support of the latest 2020-12 draft! This allows anyone to describe data structures in more detail and enhances compatibility with external tooling.

Another huge win will be for folks that need to describe Webhooks and they’ve been requesting this for some time.

One of the changes that doesn’t seem to get talked about much is the fact that you don’t _need_ to have a top-level `paths` element, you can just describe `components` and that’s still a valid OpenAPI document. That’s a huge step forward for reuse. So anyone who has lots of OpenAPI documents and is experiencing the pain of repeating information with all the problems that attracts, should be making the jump to 3.1.

— What’s your vision for the future API stack 1-3 years out?

The main problems being encountered today on the API provider side are those of managing scale and decreasing time to market, so I think Specs and various description formats play a huge role by acting as a source of truth for how our services work. I hope to see tooling that uses declarative documents to inform the entire API-building lifecycle, from ideation and design, to building tests, creating deployments on multiple environments and setting up monitoring/analytics tools – all based on the same source of truth!

On the API consumer side, we are still sending developers to documentation that can vary in quality and completeness. Humans are great at dealing with ambiguity and hopefully they’ll reach out when they have a support question. But increasingly services are consumed and discovered by machines, so I hope to see tooling that helps non-humans discover and understand the capabilities of APIs.

OpenAPI Resources

To learn more about participate in the evolution of the OpenAPI Specification: https://www.openapis.org/participate/how-to-contribute

About the OpenAPI Initiative

About Linux Foundation

Mar 10

Love0

OpenAPI meets SLA

By Andrew Bringaze Blog

This post is authored by Dr. Pedro J. Molina, Founder at Metadev & Member at ISA Group, University of Seville.

The Special Interest Group on SLAs inside OpenAPI is working to create an extension to define Service Level Agreements for API.

The latest work of the group was recently presented to the OpenAPI Technical Steering Committee for feedback and to ensure alignment with general policies.

The SLA4OAI working group needs your help to begin realizing these benefits in practice as an extension to the OpenAPI Specification. This post will explain what an SLA is, why it matters, and how new tooling can help solve important problems faced by all API providers today.

What is an SLA?

SLA is short for Service-Level Agreement, and it defines a set of metrics and constraints regarding service availability, quality of the service like minimal and maximal throughput, latency, quotas, rate-limits, etc.

Such constraints are applied to specific endpoints or operations (resources) inside an API.

These constraints can optionally be grouped in several plans and can have price.

Diagram showing SLA as the starting point with branches to a Plan, which decomposes to Pricing, Availability, Rate, and Quota, and a separate path to Metrics and Resource/Endpoint. The paths converge. — SLA relation to Metrics, Constraints, and Plans

The problem to solve

The API industry adopted OpenAPI to move from an informal to a formal definition of APIs that can be consumed by humans for documentation and machines for automation.

In the same way, commercial APIs often have an SLA described in informal language published over HTML pages or PDF docs, hardly usable by machines.

Therefore, a need for a standard to help to describe SLAs is pretty clear.

Use Cases with APIs

Having a standard format to describe SLAs for APIs will enable the following Use Case scenarios, to cite a few:

SLA Documentation: to describe the limits, rates, quotas and expected availability, and how they apply to different endpoints.
Description of Plans and prices: explaining different usage plans and costs.
Feature and Cost comparison based on (2): allowing the comparison of alternative APIs based on availability and quality features.
SLA Testing tools: to check if a given limit is applied by the API as documented.
SLA Measure: to check the metrics are inline with the SLA contract declared.
SLA Enforcing: to implement quotas and limits as a middleware for an API.
SLA compliance tracking (globally or per user): to measure the degree of real compliance of an API with the SLA respect to the theoretical one.
Automatic calculation of combined SLA for composed services. Several API can be used together to create complex services. SLA properties for the composition can be derived from the expected SLA from the simple components.
Easy setup of SLAs in API Middleware tools. Some Middleware tools provide features to implement SLA concepts like metrics, limits, quotas, rate limits, etc. Having a standard & formal way to define it will simplify the initial configuration of such features.

Current Specification

After months of work the Special Interest Group (SIG) generated the consensus to create a minimal version 1.0 for people to start using and for providing feedback.

You can take a look at the complete SLA specification.

Early feedback, roadmap, and open issues

SLAs definitions have an entity per se to be described in an stand-alone document apart from your OpenAPI definitions. For example, APIs described with AsyncAPI may also benefit from SLA descriptions.

Some open design questions where we would appreciate community feedback include:

What is the best way of representing SLA information? There is an open discussion about if we should extend the OpenAPI document directly or if we maintain the document apart and then use references to API operations. This can be achieved using different techniques like embedded extension, patch/merge mechanisms, overlays. All of them provide pros & cons. Therefore, we are evaluating trade-offs here.
SLA definitions need to reference endpoints. REST endpoints contain a URL plus a HTTP Verb (or alternatively, can be referenced by an OperationId). AsyncAPI operations will differ for sure. A reference mechanism needs to be chosen to allow pointers to specific API operations at OpenAPI, AsyncAPI or others.
Usually constraints and policies apply to a set of endpoints. Instead of enumerating all of the endpoints one by one, a mechanism based on globbing (*), or Regular expressions would be very useful to briefly describe all the endpoints affected by a given limit. OpenAPI tags were also suggested as a way to apply the limits.

Call for Implementers

Time for action has arrived!

Implementers can start building new exciting tools targeting today problems that can put in practice the usage of the extension to show its usefulness. Inside the SIG we will start also doing so very soon just to show a couple of examples of use.

So if you are interested, please feel free to ask for details and reach out to the SIG about your plans to implement it. We plan to maintain a list of related tools using the SLA spec.

To know more

Current SLA4OAI Spec
Wiki and working drafts
SLA-SIG Mail List
SLA4AOI Presentation at TSC: slides & YouTube video
Paper: The Role of Limitations and SLAs in the API Industry (ESEC/FSE ’19)

Acknowledge

Thanks to all the members taking part of the SLA SIG: Tim Burks (Google), Dave O’Neil (Apimetrics), Paul Cray (Apimetrics), Hyungjun Lim (Google), Khushan Adatiya (Google), Fran Mendez (AsyncAPI), Emmanuel Paraskakis (Independent), Phil Sturgeon (Stoplight), Nikhil Kolekar (Independent), Prithpal Bhogill (Google), Madhurranjan Mohaan (Google), Isaac Hepworth (ex-Google), Scott Ganyo (Google), Kin Lane (API Evangelist), Mike Ralphson (Independent), Jeffrey ErnstFriedman (OpenTravel Alliance), Antonio Ruiz-Cortes (ISA Group/University of Sevilla), Pedro J. Molina (Metadev & ISA Group) and Pablo Fernandez (ISA Group/University of Sevilla).

Thanks also to the TSC and OpenAPI Initiative members for encouraging us and providing the resources and feedback to make this possible.