In our ongoing effort to spread the word of Swagger, the Swagger team recently launched SwaggerHub, an online service that integrates the core Swagger tools (UI, Editor, Codegen, Validator) into a collaborative platform aiming to make it much easier to get started with Swagger and its tools. In this post, I'm going to focus on the corresponding API exposed by SwaggerHub that allows you to search for, retrieve, create and update Swagger definitions in the SwaggerHub registry. This allows you to:
- integrate search and retrieval of Swagger definitions from SwaggerHub into existing API tooling
- save Swagger definitions directly to SwaggerHub
The SwaggerHub API is available at https://app.swaggerhub.com/apis/swagger-hub/registry-api/ and its Swagger 2.o definition is available at https://swaggerhub.com/api/swagger-hub/registry-api.
SwaggerHub API identifiers
Before we dive into the API itself, let's quickly look at how SwaggerHub identifies APIs - since this "scheme" is used across the board in both the API and on the SwaggerHub itself.
Each Swagger definition in SwaggerHub is identified by the following values
- owner - the account that owns the API
- api - a unique identifier for the API under the owner account
- version - a unique version identifier
In both the API and the SwaggerHub application, these are combined as path segments in the above order which allows you to link directly to an API on SwaggerHub and its API using either:
https://swaggerhub.com/api/{owner}/{api}/{version}
or
https://api.swaggerhub.com/apis/{owner}/{api}/{version}
For the SwaggerHub API, these endpoints are:
If you omit the version at the end you will get slightly different results:
- the web version will show the default version of the API (which is configurable in the API settings)
- the api version will return an apis.json listing of all versions of the API
apis.json
Many of the GET calls to the SwaggerHub API return a list of APIs in apis.json format. For example, https://api.swaggerhub.com/apis/swagger-hub/registry-api will return a list of all versions of the SwaggerHub API. You can read about the apis.json format on the apisjson.org website. Each item in the listing above contains a number of custom "X-??" properties specific to SwaggerHub:
- X-Version: the version in SwaggerHub of the corresponding API
- X-Created: when the version was created in SwaggerHub
- X-Modified: when the version was last modified in SwaggerHub
- X-Published: if this API version has been "published" on SwaggerHub (indicating it is in finalized state)
For this specific listing you should get (at the time of this writing) 3 items in the result; versions 1.0.0, 1.0.1 and 1.0.2 - with corresponding metadata.
Authentication
Most of the resources exposed by the SwaggerHub API do not require an authentication token - the only one that currently does is the POST to /apis/{owner}/{api} which creates/updates the specified version (more about that later on). To make this call you need to provide an "Authorization" HTTP header containing the API-Key that you can get via the SwaggerHub UI, using the following steps:
- select Settings in the top right menu
- choose API-Key to the left
- click Create API-Key
Not only will this key allow you to post new/updated APIs under your account,it will also add some extra features to searching and API listings:
- an additional X-UserRole apis.json property telling what role the authenticated user has for the specific API (owner, edit, view)
- the possibility to specify filter=user as a query argument to the API search call, which will return only those APIs that the authenticated user has access to either as owner or collaborator (the X-UserRole property will be either "owner" or "edit")
Searching the SwaggerHub Registry
Ok - let's get straight to it - the base resource for the SwaggerHub API is at https://api.swaggerhub.com/apis.
This resource will return a paged list of all public APIs in the SwaggerHub registry (at the time of writing all APIs are public - but this will surely change in the near future). As indicated by the Swagger definition, a number of query arguments are available for filtering:
- query: searches on owner, name, swagger.info.title and swagger.info.description of all APIs
- tag: return only APIs with the specified tags
- state: return only APIs with the specified state
- page and limit: paging
- sort and order: sorting and ordering (!)
So, for example, if you want to find published finance APIs you would call
which at time of writing returns one API - yay!
If you want to narrow down the search to only APIs for a specific owner, add that to the path as described in the swagger.json:
You might notice that the results you get from the API calls above are the exact same you'll see in the SwaggerHub UI, which is simply due to SwaggerHub under the hood using this same API for all its API search/retrieval/update functionality.
API Versions in Search Results
As you can see, only one entry is returned for every {owner}/{api} - you won't get entries for each version of that API. The default version of the API is returned in the X-Version apis.json property together with a link to its swagger.json in the Swagger property. The X-Versions property is added also, containing a comma-separated list of all version of that API; the published versions are prefixed with an asterisk.
For example, fehguy's home automation project has the following property in the above listing:
This shows that the default version is set to 1.0.0, but there are other versions available (1.0.1 and 1.0.2). It also shows that the only version that is published is 1.0.1.
Adding an API id to the path will show all versions of that API. For example, the following returns all version of the SwaggerHub Registry API:
https://api.swaggerhub.com/apis/swagger-hub/registry-api
Retrieving API definitions
Retrieving API definitions is straight-forward as has been shown above. Just use the endpoint https://api.swaggerhub.com/apis/{owner}/{api}/{version} to retrieve the Swagger definition in either JSON or YAML format (the default is JSON - set the Accept Header to "application/yaml" for the YAML version). If you want to target a specific format directly you can append either swagger.json or swagger.yaml to the endpoint. For example, the JSON version of the SwaggerHub definition is available at https://api.swaggerhub.com/apis/swagger-hub/registry-api/1.0.0/swagger.json.
Creating / Updating API definitions
Once you have your API-Key in place as described above, you're ready to both create and update Swagger definitions in the SwaggerHub Registry. Simply POST the actual Swagger 2.0 definition to https://api.swaggerhub.com/apis/{owner}/{api}.
The following rules apply:
- You can only update/create APIs under your account - i.e. with your username as owner.
- For now, the file must contain syntactically valid YAML or JSON content.
- The version of the API will be extracted from the version property in the Swagger definition - if it is missing or invalid, the definition will be rejected.
- If an API version already exists with that version, it will be updated with the new definition (unless that version has been published - in which case, the update will be rejected).
That's it!
Simple and straight-forward - right? You can play with the API either directly in your browser as described above (since most calls are GET calls) or you can use the integrated Swagger-UI in SwaggerHub at https://swaggerhub.com/api/swagger-hub/registry-api/1.0.0/ui (notice the "ui" at the end - it will automatically select the Swagger-UI tab in the interface).
Now woo us with your integrations - we'd love to share them on http://swagger.io. If you want to see an actual example integration, have a look at the source code of the Ready! API SwaggerHub plugin available at https://github.com/SmartBear/readyapi-swaggerhub-plugin.
Swagger on!