FAQ
Here are answers to frequently-asked-questions about API Hub for Design. Don’t see what you’re looking for? Visit our Community forum.
What is API Hub for Design for?
API Hub for Design is an integrated API Development platform, built for teams, that brings the core capabilities of the Swagger framework to design, build, document and deploy APIs. API Hub for Design enables development teams to collaborate and coordinate the entire lifecycle of an API with the flexibility to integrate with the toolset of your choice.
Is API Hub for Design free?
APIs make the world a better place for developers, and API Hub for Design has been designed to allow users to take advantage of a lot of its functionality, for free. There are premium features which do cost money, and those can be purchased with a monthly or yearly subscription. You can always downgrade to free if you want.
To create APIs, you’ll need to create a API Hub for Design account.
But I use GitHub / Bitbucket / GitLab, how is this different?
Source control is great for source. But API definitions are not quite the same - they deserve their own, first-class treatment. SwaggerHub works in conjunction with version control systems, so hunting through source code should no longer be necessary.
SwaggerHub does allow connections to GitHub, GitLab, Bitbucket, Azure DevOps Services, and Azure DevOps Server. See here to learn more about our integrations.
My APIs need to be private. What can I do?
Private APIs are available to organizations on paid plans. There are different plans based on the number of APIs and collaborators you’ll need. You can always start a free trial to try our various features. Visit the Pricing page for details on plans and trials.
I want to upgrade my plan. What are the payment options available?
We accept payment via Discover, MasterCard, and Visa. For every transaction, you will receive an email receipt from API Hub for Design to your registered email address.
Using API Hub for Design
What browsers can I use with API Hub for Design?
API Hub for Design and API Hub for Design On-Premise work in the latest versions of:
Google Chrome
Mozilla Firefox
Apple Safari (on macOS only)
Microsoft Edge
Other browsers and older versions might work, but they are not officially supported or tested.
What does Publishing an API do?
When you create an API and make it available for users to consume, you are creating a contract for them. They rely on that definition to work a certain way, and breaking changes will potentially break their integrations.
Publishing an API is specific to a single version of an API. You should do so when the API ships and users can rely on the signatures. It tells your teams and consumers that your API is in a stable state. Once published, it is read-only and cannot be changed.
When published, you should consider making changes in a new version of your API.
After you publish, you may want to update the defaul version of the API. This is what is shown in search results, or when someone navigates to your API directly without a specific version number. You can Learn more about versioning.
Of course, there are always unforeseen situations where you may have a typo or need to make an emergency change. You can Unpublish your API but please do so carefully. Trust with your users is precious!
Does API Hub for Design support versioning?
Yes, you can version APIs, and deprecate old, outdated API contracts. You can learn more about versioning here.
What is the difference between Name and Title of an API?
The Name field of the API is used to uniquely identify the API in API Hub for Design. Consider this part of a permalink to the API definition. It is also used for programmatic access to your definition through the API Hub for Design CLI, API Hub for Design Registry API, and other tools.
Collaboration
Is there a limit to the number of collaborators I can add to my API?
Yes, the number of collaborators is limited, and is based on the tier you’re in. Visit the Pricing page for details on the number of collaborators.
How can I use API Hub for Design with my Company?
API Hub for Design supports the concept of organizations. Each organization can have teams which will let you add users to logical groups. An API can be given permissions to individuals or in bulk to teams.
I need to access my definitions programmatically. How do I do it? What if they’re private?
You can always reach public APIs from the public API Hub for Design API:
In simple terms, your API definitions can be accessed through this pattern:
https://api.swaggerhub.com/apis/{owner}/{api}/{version}
You can always navigate all your APIs by going here:
https://api.swaggerhub.com/apis/{owner}
This returns a response in the apis.json format.
For protected APIs that you have access to, you can get an API key from API Hub for Design and use it to access protected API definitions. To retrieve an API key, go to Settings > API Keys. You can then generate an API key which can be used as a header when accessing your data. For example:
curl -H Authorization:YOUR_API_KEY https://api.swaggerhub.com/apis/swagger-hub/registry-api/1.0.59
Will return a JSON version of this definition. If you want YAML, tell it with the Accept
header:
curl -H Accept:application/yaml -H Authorization:YOUR_API_KEY https://api.swaggerhub.com/apis/swagger-hub/registry-api/1.0.59
Important
The API key has access to your data, so keep it safe!
I generated a client SDK. Now what?
This depends on the language that you’re working with. In general, the client SDK is not useful on its own- you’ll want to use a program to call it directly. Each language and framework has different options for usage. Check out the README.md
in the output files - it should help get you started.
Integrations
What are integrations?
Integrations are free add-ons to your API definition on API Hub for Design to improve and expand its functionality. These Integrations help connect your API to a host of third-party tools which allow you to go beyond just API design on API Hub for Design! You could sync your definition with a GitHub repository, quickly generate a mock for your OpenAPI definition or create a webhook to trigger for certain events on API Hub for Design!
Can I add multiple Integrations to the same API?
Yes, you can add multiple Integrations to the same API. The Integrations could be different, for example, an API can have a GitHub Sync and a Webhook integration enabled. An API can also have the same integrations enabled twice. For example, two different Amazon API Gateway integrations can be added to the same API to sync the API with two separate Gateway instances.
Does API Auto Mocking allow for adding business logic?
No, in its current state, the mock generated by API Auto Mocking cannot send specific responses based on input.
Domains
What are Domains?
Any API designer knows that API development involves a lot of reusing and rewriting definitions and descriptions. Domains are a collection of such reusable components, which can then be referenced from other APIs and Domains. Some examples of components that can be stored inside a Domain are:
Definitions
Path Items
Parameters
Responses
Users can create and version Domains, and then define the components inside them. The components can be referenced from other APIs or Domains, either by the user or the collaborators on the API. Domains can also act as a control center for multiple APIs. One change in a Domain can quickly transmit the change across all the APIs which reference the Domain, thus allowing for faster API development and collaboration.
Who can view my Domains?
Domains can have two visibility levels: private and public. As the names suggest, public Domains can be searched for, viewed, referenced and forked by other API Hub for Design users, while private Domains can only be viewed and worked on by you and the collaborators you’ve added.
Can I reference other Domains from my Domain?
You can reference your own Domains, public Domains, or private Domains shared with you by other users. Currently, Domains require absolute references to other Domains. Just follow the syntax below to reference one Domain from another.
# OpenAPI 3.0 $ref: 'https://api.swaggerhub.com/domains/{owner}/{domainName}/{version}#/components/{componentType}/{componentName}' # OpenAPI 2.0 $ref: 'https://api.swaggerhub.com/domains/{owner}/{domainName}/{version}#/{componentType}/{componentName}'
How can I search for other Domains?
Public Domains can be searched, viewed, referenced and forked by other users of API Hub for Design. Users can use the Type: Domain filter in the search bar to search for some neat public Domains on API Hub for Design, published by other users.