As a developer of microservices, it would be very comfortable if I could easily compare different versions of one service's API. They could either be automatic diffs of the spec or, better, manually created changelogs between versions that the service's maintainers would have to create.

Users should be able to give permissions on specifications they've created. There should be three permission levels:

• view - the user can view the specification
• edit - the user can edit the specification
• admin - the user can give permissions for the specification

Permission settings should be possible by clicking on an icon within the icon bar in the specification overview.

Sometimes I, as a developer, want to "pre-publish" an in-development version of a spec to show the current changes or to test it, similar to artifact releases. This will help me to discuss changes with developers of other services, for example.

Such in-development versions must be appended with "-BETA[\d]" or "-RC[\d]", for example "2.1.0-BETA1" or "2.1.0.RC3".

Differences to the stable versions:

• The main version of a spec should be the latest non-snapshot. Only if you unfold it, you can see the snapshot-versions.

Based on #12, a visualization should be possible. The easiest is to graphically show consuming and consumed artifacts for one service.
However, we could think about visualizing the whole microservice flotilla.

As a developer, I don't want a specific spec version of a service to change, so that communication is easier and clearer. However, there should be support for "SNAPSHOT" versions that are not stable and are allowed to change. I can use these for the development of the next spec version and share them even in their non-final state.

Spec versions can be defined as a snapshot by appending "-SNAPSHOT" to the version, for example "4.1.3-SNAPSHOT".

Snapshots are generally considered pre-release versions and should behave as such (see #63). Additionally, the have the following properties:

• They are not immutable and a different spec with the same version can be uploaded. It overwrites the previous content.

A global search function should be implemented, providing a search over all metadata and all contents of specification files.

A search-bar should be displayed in the header-bar and search results should show up as a pop-down list when the search term is entered.

Pact looks like an interesting tool that could be integrated with ApiCenter. To evaluate its usefulness, we should test our own interface with it.

As a developer of a service whose spec is hosted in ApiCenter, I'd like to receive notifications for events - for example, if one of my dependencies updates its spec (see #12).

Implement an architecture that allows to send specific notifications to specific users/user groups. The notification should be triggered in the backend and shown in the frontend - they should be stored per user to show the user a list of all received notifications.

As the developer of a nice but quickly changing web service, I want some way to automatically update the spec on my company's ApiCenter without having to do anything manually. This will make it effortless to keep ApiCenter up to date with the latest specs, which will in turn increase its usefulness.

There should be simple command line client that can upload a new version/specification of a service. It should be possible to integrate it with Maven and Gradle so that the spec can be uploaded with each build or deployment.

Of course, this means that there must not be any manual interaction. We need to find good defaults or another workaround.

Make use of a more opinionated code format tool like Prettier (https://prettier.io/) for the TypeScript-Frontend-Code

Currently a GET for a non-existent specification in the webapp produces only toolbar + white page, with no indication of what has gone wrong.

The solution here may prove helpful (though ApiCenter's SQL dialect doesn't support PostgreSQL string_to_array)

Configure a Release-Plugin for Gradle and tag specific commits with version numbers.

Use something like "Prettier" for Kotlin

When selecting a specification in the overview, the specification is not shown.

It tries to request the specification via /api/v1/service/{servideId}/version/{versionId}, which is an unknown path in the backend.

Add ArchUnit Tests for basic arch rules

Instead of a "specification" having "versions", it should rather be a "service" having "specifications" (which might differ in their "version" or "language"). As a user, I can better understand these terms because they are more intuitive.

As a interested potential user, I'd like to try out ApiCenter without needing Atlassian Crowd so that I can easily see what it is about.

We should offer a pseudo authentication service that allows anyone in without a password, and make it the default.

Add possibility to have different versions of Specifications. These versions should be grouped together and additionally be associated in the UI.
Versions should be taken from the metadata fields in the OpenAPI specification (automatically assigned and updated).

When I start the Application for the first time I want an example to show up in the UI

Distinguish on specification overview between "general" specifications and specifications created by the logged in user. First of all, there needs to be an association on the data model and within the backend domain. There are some possibilities on how to distinguish your own and other specifications in the frontend:

• Show your own specifications on top of the specification list
• Somehow visually tag your own specification
• Provide two seperate lists of specifications (e.g. "All Specifications" & "Your Specifications") where you can switch between both of them via tabs

Just calling npm install for the first time results in these warnings:

npm WARN [email protected] requires a peer of acorn@^6.0.0 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of popper.js@^1.14.7 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of graphql@^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of graphql@^0.6.0 || ^0.7.0 || ^0.8.0-b || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of graphql@^0.11.0 || ^0.12.0 || ^0.13.0 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of graphql@^0.11.0 || ^0.12.0 || ^0.13.0 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of graphql@^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of graphql@^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of graphql@^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of graphql@^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of typescript@^3.0.3 but none is installed. You must install peer dependencies yourself.

We should explicitely add those.

ApiCenter should be open for all kinds of APIs, not just Swagger. One good candidate should be GraphQL: There exists a single specification file for the types. Interestingly, it doesn't appear to contain a name, version or description (this should be added manually when uploading a spec file).
For the detailed view, we could use Graphiql (if the license is okay).

As a dev I want to persist my decisions so that other developers are able to understand why I have made certain steps.

As a developer I want to have access to the already made decisions in the project so I can understand their code

Extend the Authentication mechanism with an OAuth2 implementation. This authentication method should be exclusively configurable (i.e. only one authentication method can be active).

It's possible (though rare) for a single file upload attempt, to cause the creation of two separate specification entities, perhaps due to switch bouncing within the mouse.

The specifications below have been assigned different ids, so there is no internal inconsistency, however this behaviour is not expected. I haven't been able to replicate the problem with a specification including the x-api-id field. That may result in an error, seeing as ApiCenter forbids version string reuse within one service's specification set.

We are using UUIDs as API identifiers as suggested by the Zalando API guidelines (https://opensource.zalando.com/restful-api-guidelines/#215). We would like to group APIs based on this identifier (currently no identifier is supported and every submitted API spec leads to a new API created, even on version updates). We will create a pull request if you also support this idea.

As a developer, it would be nice to see in which environment (development, staging, production) a specific version of a service is deployed. This could either be found out automatically (be sending a request to a specific endpoint to see which version is deployed there) or set manually.

The automatic way would mean that for each service, the maintainers would have to specify the possible URL per environment, and ApiCenter would send requests to them to receive the deployed version.

As a user, I'd prefer elements of the documentation to be embedded within the app, eg. describing the purpose of buttons. ApiCenter's frontend already imports ng-bootstrap, which includes tooltips, so potentially something along the lines of this quick mock-up:

(This tooltip only appears on mouse hover, print-screen does not include the mouse cursor.) Perhaps have a global switch in a user's account preferences, to enable/disable all help messages once the user is accustomed to the interface.

Docs

For every release: publish to DockerHub

As the developer of one microservice in a fleet of others, I'd like some tool that can keep track of dependencies between our services. For example, I would like to easily see which services use my API (and in which version). Then, I could gather feedback from these developers.
Also, one could draw a graph of dependencies to check for circles or bottlenecks.

When adding/editing specifications, it should be possible to specify all other specifications that this specification depends on.

This feature, together with #11, can make it possible that you're notifified when one of our dependencies uploads a new spec version.

When the user clicks on a link with a different domain (in this case a link to the CommonMark specification), then uses the browser back button to return to ApiCenter, Spring gives a 403 Forbidden response.

This happens in both private and non-private browsing windows in Chrome & Firefox. However if in a non-private window, opening a new tab to ApiCenter's homepage (or just pressing the browser back button enough times to fetch the homepage) will succeed (ie. no 403 response).

If ApiCenter is used to manage relationships between services (#12), then it should also be able to work with artifacts that only consume APIs but do not offer one themselves (f.e. frontends).

One way to do this could be to re-define API to "interface" in general, so that "Frontend/Web GUI" is one possible type besides OpenAPI etc.

Upgrade the current version of Angular (5.2.0) to the most current version

Explore mutation testing as an alternative build-check as opposed to line/statement coverage. For Kotlin we could use http://pitest.org/

Frontend compilation generates a series of warnings of the form:

Module parse failed: Unexpected token (11:12)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
|  */
| 
> import type {
|   ASTNode,
|   DocumentNode,

Others with the same problem (open issue), although the workaround posted there did not work for me.

Add a button that adds the possibility to download stored specifications.

Ideally, you should only have to deploy one artifact instead of backend and frontend separately. Maybe the frontend can be included in the static resources of the backend?

There should be a possibility for users to create an account and sign in/sign out. This should be done in a modular and extendable way, such that other log-in mechanisms (e.g. via Single Sign-On) are also supported.

User and permission management should be implemented by using Spring Security (https://spring.io/projects/spring-security).
Login should (by now) be possible via Atlassian Crowd SSO (https://www.atlassian.com/software/crowd).

HTML5 browser storage (localStorage and sessionStorage) is not a secure place for sensitive information like session tokens, as any Javascript on the page can access their contents, and may be vulnerable to XSS, see here.

Also, localStorage is shared across private browsing windows, meaning multiple sessions are not possible, see here.

Useful for implementation

As a developer with a penchant for automatic tooling, I want my ApiCenter-Gradle-Plugin to automatically push the current spec when deploying or releasing so that ApiCenter always has the latest version. However, ApiCenter returns an error code if I try to push a version that already exists even if the content hasn't changed.

I want ApiCenter to compare the content of my new spec against the content of the already uploaded spec with the same version and return a HTTP code 202 (Accepted) if they match. Only if they have actually changed should ApiCenter send a 409 (Conflict) error.

After sending a POST request to /specifications, the returned ID in the JSON is not the ID stored in the database.
GET /specifications on the other hand returns the correct IDs.

The column spacing changes slightly between the state of having no specifications, and >=1 specification(s). It's visually a bit jarring. These were taken with the same browser viewport before and after.