The API Page: Quality Evidence for One API

Overview

Information about one API is usually spread over several screens: its tests here, its security findings there, its mock somewhere else. The API page puts it together. It reads what the other areas already hold, so there is nothing extra to maintain.

For one API, the page joins:

• functional tests and their latest results
• security checks and open findings
• mocks
• load tests and their verdicts, and performance objectives
• workflows that call it
• requirements that trace to it

The page is computed each time you open it. It is never stored as a separate copy.

How to read the numbers

The page follows a few plain rules, so a number never reads better than the evidence behind it.

• A number carries what it is out of. You see "3 of 5 tests passed", never a bare percentage.
• No evidence is not "clear". "No finding open" does not mean "secure", and the page says so.
• The worst result wins.
• Old results read as not run. A result older than 180 days counts as not run.
• A part you cannot read is left out. You see a dash or Left out, never a zero.
• There is no overall score.

Step 1 — Find the API

Open Overview in the header. It lists the APIs of the project you chose. Then do one of the following:

• Choose an API in the list.
• In Discovery, open Inventory and use the Open its API page button under the row's evidence. The Quality evidence column also shows chips for tests, security, mock and load.
• Choose an API in the dependency graph.

Step 2 — Work through the tabs

The tabs are Overview, Tests, Security, Performance, Mocks, Workflows, Requirements, Dependencies, Changes, Analytics, Governance and Discovery.

• Overview gives the status words, ranked recommendations, Add this API to an application, the applications that use it, and Download report.
• Tests, Security, Performance, Mocks, Workflows and Requirements list what is behind each number. An empty tab says what is missing and what to do. It is never blank.
• Dependencies shows what comes before and after this API. See API dependencies.
• Changes shows what specification changes would touch, and the release verdicts that were kept.
• Analytics shows how often the API is called, and Governance shows where it is in its life. See API governance.
• Discovery shows which source found it.

A tab you may not open is not there, and the page does not hint at what sits behind it.

Recommended actions

The recommendations on the Overview tab can offer: Generate tests, Create a mock, Add it to a load test, Run its security checks, Build a workflow with it and Open its API page. Each one opens the owning screen already pointed at this API, or shows the assistant's offer card. Nothing is made or run until you confirm.

Step 3 — Find the APIs that need attention

The Overview list is the project home for its APIs.

• Filters: All, No tests, Failing, No mock and Open findings. Open findings appears only where Security is available.
• Search by Name or path.
• Group by: None, Team, Business domain, Lifecycle or Attention needed. Every API is in exactly one group, and a gap reads as a gap, for example No team set.
• Chips for Tests, Security, Mock and Load show the state of each part.

With Professional, Trial or Enterprise, the list is titled API by API and sits under the project's release verdict. In Citizen Developer, or when the verdict cannot be read, the same information is drawn as a table.

Act on several APIs at once

Tick APIs in the list. The bar shows "N of M APIs ticked" and offers Tick all N. The bulk actions are:

• Generate tests for these
• Create mocks for these
• Run security checks for these
• Add these to load tests
• Add these APIs to an application

You can act on at most 25 ticked APIs at once. Each action shows an offer card first, and nothing runs until you confirm. The same permissions and production protections apply as for any other way of doing it.

Compare all your projects

With no project chosen, Compare all your projects shows one row per project you can see, with the number of APIs in each state, for example "12 of 40" with failing tests. One read covers up to 25 projects and 3,000 APIs, and Show more reads the next ones. This is a screen, not a downloadable report.

Step 4 — Download a report

On an API's Overview tab, select Download report and choose PDF or CSV. The report holds who the API belongs to, how each part stands with what it is out of, and the API's tests with their latest result. It also lists open security findings, load tests with their verdict, performance objectives, mocks, workflows, requirements, and how many other APIs it is linked to.

• A part you cannot read is listed as Left out, and nothing from it is in the file.
• A long list stops at 200 rows and says how many were left out. The workflow list stops at 10.
• There is no overall score in the file.
• You need permission to export reports in that project. Every download is written to the audit log.

Applications

An application groups APIs that belong together. Add an API to one from the Overview tab with Add this API to an application. Applications are made and managed in Discovery, so they need the API Discovery add-on. See API Discovery for how they work.

Troubleshooting

• A tab is missing. You may not read that part of the project, or your plan does not include it.
• A number shows "Left out". You do not have access to that part. It is not zero.
• A result looks old. Results from the last 180 days count. Run the tests again to refresh them.
• The verdict card is missing. The verdict is for Professional, Trial and Enterprise.

Related articles

• Release verdict: is this API ready to release?
• API dependencies
• API Discovery
• Managing projects: browse features and endpoints