I’m working the great feedback we've had on APIs.json, an adding everything to the Github issues for consideration in the next version. Today I’m spending a little time thinking through the big picture of APIs.json, and some of the building blocks I'd like to see reflected when API providers generate their APIs.json.
Each API listed in an APIs.json has what we are calling: "Properties Elements”. The properties element is a collection, with two values: type and url. While we provide you with a base set of property element types you can reference:
- Swagger
- RAML
- Blueprint
- WADL
- WSDL
- TermsOfService
- InterfaceLicense
- StatusPage
- Pricing
- Forums
- AlertsTwitterHandle
Our goal is to continue providing, “reserved” types that we recognize, while also leaving properties elements, being as organic as possible—meaning you can define your own references, and tell the story of why these are important building blocks in your own API strategy. We will continue adding the best properties we see being used, to the APIs.json spec.
To prepare for the next version of APIs.json, I want to have the next list of reserved property types. Working from my list of API management building blocks I’ve identified X I’d like to see in the next version:
- GettingStarted
- FrequentlyAskedQuestions
- Signup
- BestPractices
- ServiceAccord
- Documentation
- Explorer
- ErrorCodes
- AuthenticationOverview
- AuthenticationTester
- CodeLibraries
- ApplicationGallery
- SoftwareDevelopmentKits
- StackExchange
- Calendar
- OfficeHours
- Blog
- BlogRSS
- Github
- GooglePlus
- Roadmap
- ChangeLog
- RateLimits
- Affiliate
- Advertising
- CaseStudies
- WhitePapers
- HowToGuides
- Webinars
- Ideas
- Labs
- Opportunities
- Branding
- PrivacyPolicy
- ServiceLevelAgreement
- DataLicense
- CodeLicense
- DeprecationPolicy
- Widgets
- Buttons
- Badges
These are the building blocks I think are important to API operations. Currently all of these will be links to human readable pages, within an APIs developer portal, but eventually I envision all of these potentially being machine readable.
I know, this is a big vision, but I intend to make it a reality. The first machine readable element on this list is the InterfaceLicense, which will reference the machine readable JSON manifest for API Commons.
Next on the list is TermsOfService, which I will be using Terms of Service Didn’t Read’s machine readable format, and applying it to the world of APIs. If there are any types you’d like to see in the next version of APIs.json, head over to the Github issue I created for this discussion, and make sure it is on the list.
