Design, development, and documentation are integral parts of releasing great APIs. In software teams, roles overlap with a constant exchange of information between different teams to build the perfect API. We will be walking you through a guide on creating and managing organizations while highlighting how to iterate and deliberate in teams on the API development process using SwaggerHub.
To complete this tutorial, you will need a SwaggerHub account. You can sign up here.
Define organizations and teams
SwaggerHub collaborative features were built keeping in mind the needs of the modern team to allow iterative and cross-functional development of APIs. This is possible by defining organizations and teams within SwaggerHub.
To create an organization, click Create New in the sidebar on the left and select Create New Organization. Specify the Organization Account Name (unique ID), Organization Email, and, optionally, Title.
Once the organization is successfully created, you can add existing SwaggerHub users as members to the organization. To do that, click in the top right corner of the organization page.
This opens the Organization Settings. Switch to the Members tab to invite users to your organization.
Keep in mind that your organization invites will be emailed to team members, and it is up to them to accept the invitation. For example, in the image below, Fernando (
fbmattos) has accepted the organization invitation while Daria (
daria) has not.
The power of an organization can be fully realized through teams, a feature that lets organization owners group members to collectively work on APIs. In any organization, you can create teams on the Teams tab of the Organization Settings screen:
To learn about organizations and teams in detail, check out our documentation.
In our scenario, the following teams will be developing the API:
API Architects – responsible for the API design.
API Documentation – responsible for documenting the API.
API Development – responsible for developing the server and client side code for the API.
We have now successfully created an organization, added members, and added them to teams.
Create APIs under your organization
We will be covering how to create an API from scratch under an organization, though it is good to remember that APIs can be imported or forked as well.
Click , select Create New API and choose your organization from the Owner list. Check out the Getting Started guide if you are new to creating APIs on SwaggerHub:
Various stakeholders manage different pieces of the development process of an API. Every API starts with understanding the requirements. Is this a private API to be used internally by the company to build better software, or is it a public facing API which could be used to drive the market forward and raise awareness of the company’s products and services?
Depending on the requirements set forth by the product owners and technical leads, the API would identify the need for APIs, be it public or private. SwaggerHub lets owners define the visibility of an API directly in the SwaggerHub Editor:
Private APIs are usually spearheaded by technical leads and development managers that recognize the need for an internal API to ease the development process of other applications within the organization. Product owners, marketing managers and technical leads usually lead the discussion for public APIs which are open to the masses for consumption. It is only when the vision, purpose and technology for the API are fully explored and set, can the API design and development team help make it a reality.
APIs on SwaggerHub, be it public or private, can have multiple collaborators associated with it. Once the API is created, from the SwaggerHub editor, organization owners can add teams as collaborators to the API with the privileges of their choosing.
Collaborators can edit the API and communicate with other collaborators via comments. Collaborators can be given the ability to edit the API (Editor), comment on individual lines of the API definition (Commenter) or simply have the ability to view the API (Viewer). Use comments to discuss ideas or point to issues in specific lines of your API definition in the SwaggerHub editor.
The API Architect and API Documentation teams, for example, can be given the ability to edit the API and add comments. The Development team could be given the ability to add comments. to discuss ideas, ask questions and point out issues in the API definition.
Iteration through versioning
Software teams release new and updated versions of their applications. These versions build on top of previous versions adding new changes or bug fixes, without rewriting existing code or syntax. SwaggerHub’s versioning system can help with this. Collaborators can define multiple versions of each API, meaning new revisions and edits can take place in multiple versions without overwriting the source.
Add a new version
Collaborators can add a new version of the API by clicking Add New Version on the API version list:
All collaborators will be given instant access to new versions, making it super simple to just continue working on multiple updates of the API. Versioning is important not just to keep track of revisions, but to also to keep the latest API concept and design updated.
Once the teams are satisfied with the API design, and all the back-end services and documentation are ready, the API can be published.
By publishing the latest version, all the users with access to the API know that the version is stable and can be safely referenced and consumed. Publishing an API version makes it read-only. However, if you need to make some important changes to a published version, you can unpublish it temporarily.
After you finalize the design and publish the API, all the collaborators get notifications and can start working on client-side SDKs and back-end services.
SwaggerHub supports generating server-side templates and client SDKs, which takes care of all the boilerplate code letting developers focus purely on the business logic.
With the design, back-end services and client SDK ready, all that is left is to deploy and manage the API, possibly, with SwaggerHub’s API Management integrations like Azure or AWS Gateway.
Using the power of organizations, teams, member roles, version control and commenting, SwaggerHub makes for a great experience for collaborative API development.