I had a great conversation with a company developing some very interesting API designs, and upon talking with them about submitting their API definitions to the commons I got a common question: When should we submit our definitions? Now or later? They will be changing often.

Of course each API development team will be different, but my recommendation is submit early on. The sooner the better. Even if your API definition changes often, it is better to showcase the design, soliciting feedback from the community, and establishing a precedent within your industry now.

You can see this in action with the Free Application for Federal Student Aid (FAFSA) API. It is an initial API definition for a potentially very complex PDF form that the Department of Education uses. As soon as the API definition was published, it was made open via Github, looking to solicit feedback from government, developers and anyone involved in the FAFSA project. This has opened up quite a bit of discussion and participation in the design from several companies, developers and allowed the overall design to move forward in new ways.

When it comes to your API design it is ok to iterate, but without sharing these stories within your industry, you run the risk of reinventing the wheel, and doing work without first receiving feedback from potential consumers, missing critical opportunities to partner with key players, and so much more. Of course, evolving your API design out in the commons takes a humble approach to API design, but ultimately you will be healthier for it.

Your API design will never be done. Why wait for some unknown date, that may never happen. Get your API definition into the commons, make your mark on your industry, open up conversation and lead with your API. To be in the commons you just submit a manifest which acts as a pointer to your API definition, allowing your definition to change as much as it needs.

We encourage you submit your API definitions to the API commons now, rather than later, and then you can confidently move forward with the iteration on your API, knowing you have declared your API design to be open licensed, and a meaningful design worth following.

comments powered by Disqus