Adding a simple first version of an ongoing shaping OAS3 spec

[didierofrivia]

In order to not only shaping but documenting the API endpoints we need to hydrate PortaFly, we need to use as base an OAS. This will also serve as a testing tool and development used as mocked data.
This PR also solves the first specification needed for Account > List

This spec is created with Apicurio and it's meant to be edited with it. More info in https://www.apicur.io/

What this PR does / why we need it:

Introduces an Open API Specification and address the specification needs described in https://issues.redhat.com/browse/THREESCALE-4731

Which issue(s) this PR fixes

https://issues.redhat.com/browse/THREESCALE-4711
https://issues.redhat.com/browse/THREESCALE-4731

BASED ON https://marvelapp.com/55343de/screen/67190787

How it looks

Special notes for your reviewer:
PLEASE, READ THE ISSUES ATTACH TO UNDERSTAND THIS PR, THERE'S DEFINITION OF WHAT'S NEEDED First @hallelujah comment is obsolete, those issues are meant to cover what he expressed there.

And if you want to see the responses, etc... you might want to check it in online spec docs like redoc or locally with said tool

[hallelujah]

I would like to know what this is solving. I mean those are responses but it is not solving anything in particular, it is a general description of something to expect (but what is this something?)

Specification

We need a general specification in order to know what we will need in those OAS 3.0 specifications
Example:

• I would like to display a list of applications in the page
• In this page I see: Contract name, contracted date, service name, service description in a tooltip, link to the service, link to the contract edit, link to the plan, what else?

Implementation

Then you come up with some implementations for the API

Solution 1

Discuss what you need inside, will implement in each of the OAS 3.0 specs for the purpose of the UI
Maybe some fields make sense to put inside the Entity even though they can be retrieved by another endpoint. E.g. the plan name (I do not know, it is an example)

• Contract is described like make your OAS 3.0 specification with those fields

  • id
  • name
  • subscribed_service_id
  • contractor_account_id The Account who contracted the plan
  • plan_id The contracted plan
  • plan_type The plan type
  • contracted_account_id The Account who created the contracted plan
  • contract_type The type of contract (Application,

• Service is described like make your OAS 3.0 specification

  • etc ...

• Plan is described like make your OAS 3.0 specification

  • etc ...

Use of Porta API

We can use the following Porta API endpoints:

• /admin/api/applications
• /admin/api/services
• etc ...

Raise issues:

• But those API are not returning the response we want.
  We will need to compose those API response
• Evaluate the complexity and where to do it:
  • It will be easier if we do it in BFF, why? how?
  • It will be easier if we do it directly in JS for now, separating the composition with the responses
  • It will be really easy to do it in Porta directly, why? how?

Evaluate the complexity of crafting the response described above

Solution 2

You decide not to put those fields inside the Contract, but then describe how you can retrieve them
and raise the potential issues like above.

Decide on an implementation

Raise issues and try to solve solution for each raised issues.
Then go for it the OAS 3.0 description and the code.

Notes

Right now we have contract instead of application.

Type	Description	Reference
Contract	Meta class for all types of contracts	Plan (Meta class)
Cinstance	The actual application	ApplicationPlan
ServiceContract	A type of contract by Service	ServicePlan
AccountContract	A type of contract by Account	AccountPlan

[josemigallas]

Rebased

[guicassolato]

Are you sure you'll only need the name of the user? Maybe a link to the user instead?

[didierofrivia]

Given the design in https://issues.redhat.com/browse/THREESCALE-4725, only the name is needed. No link for the admin user. It might be needed for the organization link that links to the account, which is not yet created. I thought about expanding the spec as we are building new resources. Does that make sense?

[guicassolato]

I guess it makes sense, yes.