)
The OpenStack API Working Group is on a mission to improve the developer experience of API users.
The roots of the group stretch back to 2014 when the community voiced a clear desire for better OpenStack APIs. Rackspace developer advocate Everett Toews was the one to ask “What’s the next step?” and things grew rapidly from there.
The team has come a long way since then – take a look at the current API Guidelines, which cover everything from metadata to errors. At the upcoming Summit, you can get involved in the discussion at the API Working Group Mitaka Cycle Roundup session on Monday, April 25 at 2:00 p.m.
Superuser talked to Toews about the head-scratchers developers face, which contributions the group needs most, and how to voice your opinions beyond the Summit.
Many people have said that OpenStack needs to expand its footprint with developers – why is this important now?
It’s always been important. It’s just that now that OpenStack has reached a critical mass, there are enough developers and operators who are motivated to automate the deployment of their applications on OpenStack to be heard. The OpenStack community needs to seize this motivation and act on it to provide a better developer experience so that people genuinely enjoy working with OpenStack clouds.
What are the biggest challenges that developers face now?
With respect to using the APIs, the three big challenges are consistency, design and documentation.
Simply trying to make sense of the different ways of doing the same thing across various APIs isn’t easy. For example, there is the concept of metadata, versioning and pagination in various APIs but they all implement it a little differently.
The design of many of the APIs isn’t ideal. For example, header usage, what gets returned when an error occurs, and representing actions.
Inaccurate or missing documentation can make it all but impossible to write code for these APIs.
All of this amounts to many head-scratching moments when you’re writing code against these APIs. You can’t reuse as much code as you like, you have to deal with all kinds of crazy corner cases, and your abstractions begin to leak. These problems bubble up through the software development kits, the command line interfaces, and even the graphical user interfaces and can lead to a bad experience at every layer.
How does the working group address those challenges?
The API Working Group Mission Statement.
To improve the developer experience of API users by converging the OpenStack API to a consistent and pragmatic RESTful design. The working group creates guidelines that all OpenStack projects should follow for new development, and promotes convergence of new APIs and future versions of existing APIs.
As OpenStack projects begin to follow the Guidelines, they create consistent, well designed, and well documented APIs.
To address the examples of inconsistency above, we created the Metadata guideline, there are multiple parts to a versioning guideline in review, and a pagination guideline in review.
To address the examples of poor design above, we created the Headers guideline, Errors guideline, and an actions guideline in review.
We also have an API Documentation guideline. However, the technology used to implement the API docs is influx and will be discussed during a Cross Project sessions at the Austin Summit (will provide a link when it’s published) and A new API definition way for Doc and Imp.
Who should get involved in the working group?
Our primary audience is OpenStack contributors. This is the community the guidelines are written for.
Naturally we’re happy to take feedback from anyone though. If you find an inconsistency throughout the APIs or better design principles to be followed, you can file a bug to create a guideline. If you find an error in the API documentation, you can file a bug.
How can they get involved beyond the Summit?
Check out the OpenStack API Working Group wiki page. It has all the details about our Communication, Deliverables, and How to Contribute.
If you’re not sure where to start, ask us using IRC in #openstack-sdks on Freenode or send an email with “[api]” at the start of the subject to [email protected].
What contributions or involvement do you need most right now from the community?
We can always use more guidelines to drive consistency and good design into the OpenStack APIs.
But right now, we need more OpenStack contributors actually implementing the guidelines in their projects. The Errors guideline is a good example. It was recently implemented in the Containers (Magnum) project and there’s a spec in review for it in the Block Storage (Cinder) project. We would love to see this and other guidelines implemented across OpenStack.
Anything else you want people to know?
The idea for an API Working Group was around long before I showed up. I was just the one to ask “What’s the next step?” Things snowballed from there. It’s the result of a lot of hard work from a whole lot of people. Cheers to everyone who has taken the time and effort to contribute.
- Exploring the Open Infrastructure Blueprint: Huawei Dual Engine - September 25, 2024
- Open Infrastructure Blueprint: Atmosphere Deep Dive - September 18, 2024
- Datacomm’s Success Story: Launching A New Data Center Seamlessly With FishOS - September 12, 2024
