APIs & API Models

With Xapi you can document API requirements, maintain API hierarchies, use Kanban-based API tracking, API management workflows, and user management.

Inside an API, there are objects. Inside a Model, there are extracted reusable/common components which can be used across multiple APIs.

Create API Designs

In Xapi, you can create APIs from multiple screens. In that case, the Collection Path may differ from one another. The best practice is to decide under which catalog you want to include the API: either the Organization-specific catalog or a Project-specific catalog.

Xapi allows you to create brand-new API Designs or Import pre-designed APIs.

To Create a New API Design

1. Log in to Xapi.

2. Select the organization either from the Profile icon or the All Organization screen.

3. From the API Catalogs drop-down, you can select either the Organization Catalogue or a Project Catalogue. Also, from the Organization Dashboard, you can directly create APIs.

4. Then click + Create and select API > New API.

5. In the New API window, fill in the following required fields.

6. Click Create. Your new API is created and displayed in the respective dashboard.

To Import a pre-designed API

1. Log in to Xapi.

2. Select the organization either from the Profile icon or the All Organization screen.

3. From the API Catalogs drop-down, you can select either the Organization Catalogue or a Project Catalogue.
   Also, from the Organization Dashboard, you can directly create APIs.

4. Then click ** + Create** and select API > Import API.

5. From the Import API window, choose the preferred way from the following options to upload the pre-defined API file.

   • Drag and drop
   • Browse

• Enter base API URL

6. Click Import. The New API window is displayed.

7. In the New API window, fill in the following required fields.

8. Click Create. The newly created API is displayed in the respective dashboard.

Search APIs

To Search an API

Xapi allows you to search your own APIs, public APIs, and APIs owned by a co-member of the respective API Catalogue, Project or Organization.

1. Log in to Xapi.

2. Select the organization either from the Profile icon or the All Organization screen.

3. From the API Catalogs dropdown, select the relevant catalog.

4. In the Search field, enter the API Name or the API Description.

5. Then click the Filter drop-down and select the API checkbox.

   The Catalog screen displays the searched API. If it is not available, the screen displays an error notice.

To View an API

In Xapi, you can view the APIs from different screens. The following guide describes viewing an API from the API Editor. From this option, you can view the important details related to the selected API.

1. Log in to Xapi.
2. Select the organization either from the Profile icon or the All Organization screen.
3. From the API Catalogs dropdown, select the relevant catalog. The Catalogue screen displays whatever API designs are available under the selected catalog Also, from the Origination Dashboard by clicking the relevant project or API catalog can view the API designs.

Or via the All Projects Dashboard and Project Dashboard, you can view the APIs by clicking the relevant project or API collection.

4. Click on the preferred API.
5. Click on the API version.

You are navigated to the API Editor screen, as shown.

Edit APIs

In Xapi, you can edit APIs, if you are the owner of APIs or you collaborate with the APIs via organization, project or catalogue. Also, only the unapproved API details can be edited.

To Edit an API

1. Log in to Xapi.

2. Select the organization either from the Profile icon or the All Organization screen.

3. From the API Catalogs dropdown, select the relevant catalogue.

The Catalogue screen displays whatever API designs are available under the selected catalogue.

5. From the selected API tile, click the horizontal ellipsis and select Edit API.

6. In the Edit API window, you can update the API Name and Description. If you want, you can change the Avatar.

7. Click Update API.

API Versions

To Create an API Version

1. Log in to Xapi.

2. Select the organization either from the Profile icon or the All Organization screen.

3. From the API Catalogs dropdown, select the relevant catalogue. The Catalogue screen displays whatever API designs are available under the selected catalogue.

4. From the selected API tile, click the horizontal ellipsis and select Create New Version.

5. In the New API Version window, fill in the following fields. Note: Fields marked with * are mandatory.

6. Click Create. You are navigated to the API Version Tooling page.

To Edit an API Version

In Xapi, you can edit API Versions, if you are the owner of APIs or you collaborate with the APIs via organization, project or catalogue. Also, only the unapproved API details can be edited.

From this option, you can keep APIs up to date.

1. Log in to Xapi.

2. Select the organization either from the Profile icon or the All Organization screen.

3. From the API Catalogs dropdown, select the relevant catalogue. The Catalogue screen displays whatever API designs are available under the selected catalogue.

   Also, from the Origination Dashboard by clicking the relevant project or API catalogue you can view the API designs.
   Or via the All Projects Dashboard and Project Dashboard, you can view the APIs by clicking the relevant project/ API collection.

4. Click on the preferred API.

5. Click on the API version.

   You are navigated to the API Version Tooling page.

6. Update the unapproved details as you permit.

   If you are the API Designer, you can change the API status among To-do, Design in progress, and Review in progress.

   If you are the API Reviewer, you can change the API status among To-do, Design in progress, Review in progress, and Done.

   If you are not the API Designer or Reviewer, you are allowed to change the API status only if the Kanban Board is not enabled for the respective API.

If the API status is updated to Review in Progress status, API designers will not be able to change the API status.

API Comments

To Add Inline Comments to APIs

Xapi allows you to add inline comments to APIs and tag project members.

1. Log in to Xapi.

2. Select the organization either from the Profile icon or the All Organization screen.

3. From the API Catalogs dropdown, select the relevant catalogue. The Catalogue screen displays whatever API designs are available under the selected catalogue.

   Also, from the Origination Dashboard by clicking the relevant project or API catalogue you can view the API designs.
   Or via the All Projects Dashboard and Project Dashboard, you can view the APIs by clicking the relevant project/ API collection.

4. Click on the preferred API.

5. Click on the API version.

   You are navigated to the API Version Tooling page.

6. Select the relevant code context to be commented on.

7. From the upper right bar click Comments. A Comments icon appears on the screen, as shown.

8. Click on the Comment icon.

9. In the resulting text box, enter the inline comment. By clicking the @ icon, you can tag a project collaborator. E.g. @Name Comment.

10. Click Add.

A success message is displayed.

Also, the comment icon is changed to a profile icon. By clicking that icon, you can view/edit the added comment.
The resulted text box displays the commented author’s name, date, and time along with the comment. See the following image.

Furthermore, you can view the added comments under the Comments section.

The tagged member will be notified via a clickable notification that includes the details of the respective API.

If you are the API Reviewer, the system will display the added inline comment details on the Activity Stream of the corresponding API designer or the tagged user.

If you are a Project Member, the system will display the added inline comment details on the Activity Stream of the corresponding project members or the tagged user.

To Resolve API Inline Comments

In Xapi, you can resolve inline comments added to the APIs by collaborating or rejecting the changes mentioned in the comment. Also, you can provide feedback in the same inline comment.

1. Log in to Xapi.

2. Select the organization either from the Profile icon or the All Organization screen.

3. From the API Catalogs dropdown, select the relevant catalogue. The Catalogue screen displays whatever API designs are available under the selected catalogue.

   Also, from the Origination Dashboard by clicking the relevant project or API catalogue you can view the API designs.
   Or via the All Projects Dashboard and Project Dashboard, you can view the APIs by clicking the relevant project/ API collection.

4. Click on the preferred API.

5. Click on the API version. You are navigated to the API Version Tooling page.

6. Click the Comments tab or the Comments icon. The Comments section or Comments text box displays the comment context and other details of the comment.

7. Follow the below steps as required.

   • Click the Thumbs-up emoji for a positive response.
   • Click the Thumbs-down emoji for a negative response.
   • Click the Edit button to add a new comment.
   • To Close the comment, from the horizontal ellipsis select Delete.

8. After the changes are done, from the horizontal ellipsis, select Resolve.

   A success message is displayed.

All the project collaborators attached to the comment thread will be informed via a clickable notification that includes the details of the respective API.

Merge APIs

Xapi allows you to merge the changes from an API file to the base API file smoothly.

To Resolve and Merge API Files

If you are an API Reviewer by following this process, you may resolve the conflicting changes between the merging API file and the base API file.

1. Log in to Xapi.

2. Select the organization either from the Profile icon or the All Organization screen.

3. From the API Catalogs dropdown, select the relevant catalogue.

   The Catalogue screen displays whatever API designs are available under the selected catalogue.

   Also, from the Origination Dashboard by clicking the relevant project or API catalogue you can view the API designs.
   Or via the All Projects Dashboard and Project Dashboard, you can view the APIs by clicking the relevant project/ API collection.

4. Click on the preferred API.

5. Click on the API version.

You are navigated to the API Editor page, as shown.

6. From the left pane, click on the ticket status drop-down and select Done.

7. In the Warning – Status Update popup, click Open Ticket.

8. From the right pane of the Kanban Board, click on the Status drop-down and select Done.

9. In the warning popup, click Yes, Open in Editor. You are navigated to the Editor screen of the merging API.

10. If no merging conflicts are found, click Commit.

11. In the Merge all Changes popup, fill the following required fields. Note: Fields marked with * are mandatory.

12. Click Merge. You are navigated to the API Editor screen of the merged API. A success message is displayed.

13. If any merging conflicts are found, the Editor page will be opened with the title “Resolving conflicts between merging API name and base API name. “

In the Code View, the right side pane displays the Diagnostics tab. Also, the conflicting lines display in Red color letters. The following symbols define the place the merge conflicts occurred and the type of the conflict.

• " < < < < < " merge API branch : This indicates the outgoing changes, which represent the code changes that the API Designer has made on the local branch.
• " > > > > > " base branch : This indicates the incoming changes, which represent the code changes from the base API branch. Will be at the end of the changing code.
• " = = = = = " This divides the incoming changes from outgoing changes in merging API code.

14. In the Diagnostic tab, resolve all the error diagnostics. The system displays a tick mark above the API conflict view of the merged API and the Mark as Resolved button is enabled.

15. Click Mark as Resolved.

If any conflicts remain, a warning popup will display. Click Ok.

You will be navigated to the merged API conflicts view in the code editor.

If no conflicts remain, the Merge all Changes popup will display.

16. In the Merge all Changes popup, fill the following required fields.

17. Click Merge. You are navigated to the API Editor screen of the merged API. A success message is displayed.

To Merge the Approved API Changes to the Main API

If you are a Platform User Reviewer by following this process, you can merge the approved API changes to the main API. You are allowed to merge your own APIs and APIs owned by a co-members of a project which you are a member or assignee. This may include exit approved API versions, API bug fixes, and API improvements.

1. Log in to Xapi.

2. Select the organization either from the Profile icon or the All Organization screen.

3. From the API Catalogs dropdown, select the relevant catalogue.

4. In the Catalog screen, click the vertical ellipsis to get the list view.

5. From the selected approved API, click the horizontal ellipsis and select Merge Changes. Or click an approved API Collection > API Version and navigate to the API Editor page. Then click Merge Changes.

Now the system compares the main branch and the API branch.

If any conflicts are found, the system will notify you with the Resolve Conflict button.

i. Click Resolve Conflict. ii. In the diff-view of the API, compare and resolve the conflicts. The diff-view displays the total number of conflicts available.

Xapi provides the following options to resolve conflicts.

• Resolve conflicts manually - This is to edit and resolve the conflicts.
• Keep incoming changes - This is to discard the changes of the main branch.
• Keep current changes - This is to discard the changes of the API branch name branch.
• Keep both changes - This is to keep both changes.

iii. After all the merged conflicts are resolved, click Mark as Resolve. iv. Enter the Commit message. v. Click Confirm Merge.

A success message is displayed and you are navigated to the API Editor page.

The Activity stream and the History section are updated accordingly.

If any conflicts are not found, you will notify with a message.

i. Enter the Commit message. ii. Click Confirm Merge.

A success message is displayed and you are navigated to the API Editor page.

The Activity stream and the History sections are updated accordingly.

Fork APIs

In Xapi, you can fork APIs and make a duplicate. You are allowed to fork your own APIs and APIs owned by co-members of a project in which you are a member or assignee.

To Fork APIs

1. Log in to Xapi.

2. Select the organization either from the Profile icon or the All Organization screen.

3. From the API Catalogs dropdown, select the relevant catalogue. The Catalogue screen displays whatever API designs are available under the selected catalogue.

   Also, from the Origination Dashboard by clicking the relevant project or API catalogue you can view the API designs.
   

   Or via the All Projects Dashboard and Project Dashboard, you can view the APIs by clicking the relevant project/ API collection.

4. Click the preferred API.

5. In the API Version, click the horizontal ellipsis and select Fork API.

6. In the Fork API window, enter the following required fields. Note: Fields marked with are mandatory.

7. Click Fork. A success message is displayed.

The API Catalog screen displays the forked API.

Watch List

To Add the User Account to an API Watch List

From this option, you can add your user account to an API Watch List having the purpose of receiving notifications related to the changes of the selected API.

You are allowed to add yourself to the watch list if you are a project member or organization member of the selected project.

1. Log in to Xapi.

2. Select the organization either from the Profile icon or the All Organization screen.

3. From the API Catalogs dropdown, select the relevant catalogue.

   The Catalogue screen displays whatever API designs are available under the selected catalogue.

   Also, from the Origination Dashboard by clicking the relevant project or API catalogue you can view the API designs.

   Or via the All Projects Dashboard and Project Dashboard, you can view the APIs by clicking the relevant project/ API collection.

4. Click the preferred API.

5. Click on the API version. You are navigated to the API Editor page.

6. Click Start Watching.

   📃

   Note: If you are the organization owner or admin, the system will display the list of members who are already on the Watch List.

   💡

   Tip: By clicking the Stop Watching button, you can remove your account from the respective API Watch List.

To Remove the User Account from an API Watch List

From this option, you can remove your user account from the respective API watch list having the purpose of blocking the API notifications.

1. Log in to Xapi.

2. Select the organization either from the Profile icon or the All Organization screen.

3. From the API Catalogs dropdown, select the relevant catalogue.

   The Catalogue screen displays whatever API designs are available under the selected catalogue.

   Also, from the Origination Dashboard by clicking the relevant project or API catalogue you can view the API designs.

   Or via the All Projects Dashboard and Project Dashboard, you can view the APIs by clicking the relevant project/ API collection.

4. Click the preferred API.

5. Click on the API version. You are navigated to the API Editor page.

6. Click Stop Watching.

Delete APIs

Xapi allows you to deprecate unnecessary API designs and keep the API Catalog fresh. In that case, the system allows to deprecation only the Approved APIs.

If you are the owner or admin of the respective organization or API Reviewer of that project, you can deprecate approved APIs.

Also, Xapi allows you to delete unapproved API designs. If you are the owner or admin of the respective organization or API Creator of that project, you can delete unapproved APIs.

To Deprecate APIs

1. Log in to Xapi.

2. Select the organization either from the Profile icon or the All Organization screen.

3. From the API Catalogs dropdown, select the relevant catalogue. The Catalogue screen displays whatever API designs are available under the selected catalogue.

   Also, from the Origination Dashboard by clicking the relevant project or API catalogue you can view the API designs.

   Or via the All Projects Dashboard and Project Dashboard, you can view the APIs by clicking the relevant project/ API collection.

4. In the relevant API design, click the horizontal ellipsis and select Deprecate API.

5. Click Deprecate.

   A success message is displayed and you are navigated to the API Catalog page.

To Delete APIs

1. Log in to Xapi.

2. Select the organization either from the Profile icon or the All Organization screen.

3. From the API Catalogs dropdown, select the relevant catalogue.

   The Catalogue screen displays whatever API designs are available under the selected catalogue.

   Also, from the Origination Dashboard by clicking the relevant project or API catalogue you can view the API designs. Or via the All Projects Dashboard and Project Dashboard, you can view the APIs by clicking the relevant project / API collection.

4. Click the preferred API.

5. Click on the API version.

6. From the horizontal ellipsis, select Delete API.

   💡

   Tip: If this API is associated with a Kanban ticket, the system will display an error message. You can either update the ticket status to Done or unlink the Kanban ticket.*

7. In the resulting popup enter the following details.

8. Click Yes, Delete.

A success message is displayed and the deleted API is removed from the list.