What do you think makes a good API Specification?

dcouldwell
Participant III

I've experienced a wide variety of approaches to how programs define their API specifications and often it leads to a number of questions such as:

  • Who owns the specification?
  • Who is the audience for the specification?
  • How will the specification be maintained as it evolves over time?
  • What format should be used to define the API Specification?

I've documented some of the best practices that the Customer Success Team at Apigee follows on engagements here but I'm keen to hear experiences from the rest of the community on the approaches being taken, what's worked well and what challenges you've faced.

2 1 444
1 REPLY 1

kkleva
Participant V

I often like you stay out of the the "Who owns the specification" conversation. My point of view is to maintain the API platform it's your teams responsibility to consistently document southbound target specifications.

I think folks overlook how important gearing your documentation toward the target developer. The guys who are maintaining or building your southbound targets often have their documentation in various formats and design specs across the enterprise.

These "Southbound Target Specifications" prove a tremendous value in promoting a HTTP inspired accounting of the system your about to transform with your fresh new northbound proxy.

A lasting API Platform specification strategy has killer southbound specs too!