It’s August, and while kids may not be returning to school for a couple of weeks, teachers are certainly starting to gear up for the year ahead. I was a teacher in my previous career, and some part of my brain starts itching to do some curriculum planning around this time every year.

Instead, we’re going to apply some back-to-school principles to your API documentation. After all, your docs are there to educate your API consumers, and there are some ideas from education that can inform your approach to docs. 

The school year always starts with formative assessments. Teachers use pre-tests and writing samples to shape their instruction for the year – there’s no such thing as a failing grade, just information that helps students focus their efforts where they need the most growth. As you grade your API program on the standards below, remember that the purpose of benchmarks is to shape your plans for improvement!

Use Specifications to Define Your APIs

Good instructional design starts with clear objectives – what should students know and be able to do by the end of a unit of study? At every stage of curriculum development, teachers reflect on those outcomes and evaluate how well they’re moving students toward the goal. Anything that doesn’t serve those goals should be set aside, at least temporarily. Students and teachers are busy, and focused attention on a smaller set of goals leads to deeper learning in less time. 

An API specification is a document that outlines what your API will be able to do – sound familiar? Like a teacher designing classroom instruction, your API teams are busily trying to serve a broad range of needs, and they’ll deliver better outcomes if they have more focus. Before you begin investing time and resources into building your API, you need to have a well-defined goal to ensure that your efforts are all aimed at your desired outcome. Creativity and innovation are welcome, but they need to be purposeful – having a clear objective helps you prioritize work that moves you toward your goal. 

Taking an objective-driven approach to your API development aligns well with an API-as-a-Product philosophy. To efficiently deliver a valuable product, you need to have a clear vision of how consumers will use it, and you’ll need to follow design and development practices that keep you faithful to that vision. Every efficiency you add to your process is an opportunity to reevaluate your goals and see where you can purposefully add more value. Set those creative ideas aside, but don’t forget them – focusing on a narrower goal now may give you more resources to fully develop other objectives later.

Standard 1: You have a simple way of defining your API objectives early in your product development life-cycle. You have practices that keep you accountable to your goals throughout the development process. If you’re not confident you’re hitting this standard, an API specification might be the place to start. 

Describe the Purpose of Each Endpoint

You’ve likely had at least one moment as a student when you asked the inevitable question: “Why are we learning this?” It’s not a teacher’s favorite question, but it is one they’d better be prepared to answer. 

Learners retain more information when they have a schema to organize information and can see the practical implications of what they’re learning. Organizing curriculum and instruction around goals is a first step; the next is to share those goals with students in a relatable way. 

Endpoint documentation can be disorienting, too, leaving potential API consumers wondering, “Why am I reading this?” or “Why would I need this endpoint?” API references need to be more than an alphabetical list of endpoints with a list of fields – developers will get much more out of your documentation if you also explain the purpose of each endpoint. 

Most API documentation will include a “Guides” section with use cases, how-to articles, and other narrative-form articles. While that’s great content to have, you can also take some simple steps to make your API Reference more valuable – create a schema for developers to understand the purpose of your API by grouping endpoints by function and providing brief examples of practical use cases. What goal might a developer achieve with each endpoint? 

If anything, clearly identifying the purpose of each element of your API is even more important than in a classroom – you are providing pragmatic education, not theoretical concepts, and your API consumers will be better served by references organized around jobs to be done.

Standard 2: Your API Reference consistently identifies the purpose of each endpoint with examples of practical outcomes. Developers can understand why they would use an endpoint and can quickly identify which endpoints will help them meet their goals. You apply your knowledge of the function and purpose of your API to organize documentation in a meaningful way. If not, you may want to consider revamping your API Reference to create a schema that makes the purpose of your API endpoints clear in user-focused terms.

Implement Style Guide Automation

This standard is really about making life easier for you. No one — teachers or API developers — should be spending their time on repetitive tasks where good automation tools could do the work instead. We’re not advocating automating everything, of course. Good teachers are constantly adjusting their plans to meet students’ current needs, and API teams should be customizing documentation and adapting product designs based on real-world applications, as we described in Standard 2. 

The purpose of automation is to make tasks that don’t need customization quicker and easier, giving you more time and focus for tasks that require your full attention. If you’ve done the work of developing an API specification (Standard 1), you’ve already done much of the hard work required to set up automated style guides. Once you’ve made the design decisions and set out your objectives and standards for how you’ll build your API, there’s no reason to manually check every part of your code for compliance – automation tools can do that for you.

An added bonus: automation done right leads to more consistency and predictability, which in turn leads to a better product for your consumers. On both sides, automation lets people focus on what really matters, which is the real-world functionality of your API. When developers spend less time dealing with inconsistency, they have more time and energy to get meaningful work done. 

Standard 3: You identify best practices for your API design and style, and use automated tools to improve compliance and reduce overhead. You free up resources to do complex, creative work that improves real-world outcomes for your internal and external API stakeholders. 

Add Context To Your API Catalog

Educators know the value of student choice in improving engagement. The best results come when students can make informed choices. Each individual comes to a classroom — or API catalog — with a unique set of needs. A teacher’s job is to provide students with the information that will help them choose the best path for achieving their individual goals. 

Similarly, your API catalog will serve your developers better if it includes context that helps them find the right path for their needs. High-quality endpoint references help API consumers know the purpose of individual elements of a given API, but what about the big picture? Developers coming to your API catalog first need to understand the distinct role of each API so they can choose the tool that best fits their unique needs. 

As for engagement, an API catalog that provides context and examples can also be beneficial. Developers have a lot of choices, probably more than most students, and they’re likely to return to resources that center their needs. An API catalog that provides a practical portal and important contextual detail is the kind of resource developers love – it lets them make an informed choice and act on it quickly.

Standard 4: You empower developers to make informed choices and act on them with developer-friendly tools. You present your APIs in an API catalog that is organized around developer needs and includes information about use cases and functionality in an easily digestible format. 

Are Your API Docs Meeting Standards?

We’re not here to tell you whether your API programs are hitting the mark – that’s a question you’ll have to ask yourself. But we’re here to help, with guidance you can use to evaluate your progress and tools to help you achieve your goals for improvement. 

At Stoplight, we’re lifelong learners – a spirit we know is shared across the API industry. As the school year gets underway, take some time to reflect on how your API programs promote learning. Are there ideas you can apply from your own formal or informal education? I used to tell my students, “There are definitely wrong answers out there, but there are a lot more right answers.” We can’t prescribe one path for every API program, but we hope that these standards can help you find approaches that work for you!