Search⌘ K
AI Features
Home
Courses
Design and Build Great Web APIs

API Sketching Tips and Tricks

Explore how to quickly sketch APIs using HTML and FORMS+JSON formats to visualize resource connections and mock HTTP requests. Understand the value of creating multiple disposable sketches for early feedback and refinement. This lesson helps you develop practical skills to prototype APIs effectively and communicate ideas with your team.

We'll cover the following...

Sketching APIs in HTML

Previously, we used HTML for one of our early sketches. It makes it easy for us to visualize the way resources connect to each other, and it also makes it possible for us to use Apiary Mock Server to share a user-friendly rendering of our sketch with other stakeholders on our team, with our clients, and so forth.

For example, here’s the Onboarding Record sketch in HTML. This is the resource that supports all the actions, like addCompanyInfo, addAccountInfo, addActivityInfo, approveOnboarding, and rejectOnboarding:

HTML
Onboarding Record [/1q2w3e4r5t]
### Show Onboarding Record [GET]
+ Response 200 (text/html)
        <h1>ITEM:1q2w3e4r5t</h1>
        <p><a href="/list">LIST</a></p>
        <p>data fields display here...</p>
        <p><a href="/1q2w3e4r5t/company">Show Company Info Form</a></p>
        <p><a href="/1q2w3e4r5t/account">Show Account Info Form</a></p>
        <p><a href="/1q2w3e4r5t/activity">Show Activity Info Form</a></p>
        <p><a href="/1q2w3e4r5t/approve">Show Approve Form</a></p>
        <p><a href="/1q2w3e4r5t/reject">Show Reject Form</a></p>

Of course, this sketch renders nicely in a browser; all the links actually work! ...