Posted on 05-29-2014
This post is an exact copy from the Swagger specification page, on the Swagger Github project. As I was reviewing the latest Swagger 2.0 release, I read this descripton, and I really felt it caputred not ust the mission of Swagger, but spoke to the essence of API design. With this in mind I wanted to re-post, as part of my ongoing coverage of the API design space.
The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, Swager removes the guesswork in calling the service.
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. Swagger-enabled APIs expose JSON files that correctly ahere to the Swagger Specification, documented in this repository. These files can either be produced and served statically, or be generated dynamically from your application.
Without going into a long history of interfaces to Web Services, this is not the first attempt to do so. We can learn from CORBA, WSDL and WADL. These specifications had good intentions but were limited by proprietary vendor-specific implementations, being bound to a specific programming language, and goals which were too open-ended. In the end, they failed to gain traction.
Swagger does not require you to rewrite your existing API. It does not require binding any software to a service--the service being described may not even be yours. It does, however, require the capabilities of the service be described in the structure of the Swagger Specification. Not all services can be described by Swagger--this specification is not intended to cover every possible use-case of a REST-ful API. Swagger does not define a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with a REST API.
This GitHub project is the starting point for Swagger. Here you will find the information you need about the Swagger Specification, a simple static sample of what it looks like, and some general information regarding the project.
comments powered by Disqus
Winning in the API Economy
|Download as PDF|
Latest Blog Posts
- Using Excel As An API Datasource And An API Client For The Masses
- Relationship Between APIs And Containers
- Real-time and Visualizations Will Be Key in Financial API Deployments
- Notification Focused Startups Within Leading API Ecosystems
- APIs That Do One Thing And Do It Well Like ZipLocate
- Which API Do I Need?
- The Expanding API Conference Landscape
- Ocotoparts Open Source Google Spreadsheet
- Andrew Nacin Of WordPress @APIStrat Chicago
- Push Button API Deployment With The Heroku Button
- WordPress Style API Modules For Government
- The Heroku HTTP API Design Guide
- What I Have Been Calling API Trends, Are Slowly Being Baked Into API Operations
- FDA Finding Their API Mojo With A New Drug Label API
- Adding PokitDok To Healthcare Research And The API Stack (Well They Did)
- Why I Am Continuing To Integrate Zapier In My Business Workflow
- Who Is Going To Build The Uber API Platform For The Sharing Economy?
- The API Focused Dev Shop
- Route SMS Messages To Google Spreadsheets Via Twilio API With TwilioSheet
- Publishing Your APIs To Product Hunt
- Providing Users With Reciprocity Tools So Important Intuit Purchases itDuzzit
- Bing Developer Assistant for Visual Studio Delivers Relevant API Code
- Average Number of APIs Used In A Modern App
- An APIs.json Collection Of API Resources Across Your Public, Partner Or Internal Resources
- One Possible Reboot Of The API Stack