[MA-96] describe getActionAgendaById API

[ghost]

Solves: [https://myaegee.atlassian.net/browse/MA-96]

First description of the API to return an Action Agenda by Id with all necessary sub-objects.

We'd like to get feedback and recommendations, as well as input on how the security should look like (we removed it for now).

[WikiRik]

I'm not really knowledgeable on OpenAPI documentation so my comments are not really specific to OpenAPI. But overall I think it looks good for a guideline on how to program this.

[WikiRik]

I would add a response of 401 here, saying that the user is unauthorized to do view the Action Agenda

[WikiRik]

I don't really understand this. If the ID is between 1 and 10 it will give an Action Agenda and otherwise it will generate an exception? Won't it generate 404 errors for every non-existing Action Agenda?

[freitzio]

That was a leftover of the base we used. This is only in the description here and not an actual limitation of the values but indeed this needs to change. Thanks for noticing it!

[HassanCehef]

Some nitpicky suggestions to make the contract a bit stricter.

With the current API, we always need to play a guessing game as to which action agenda ID exists.
Two things:

• Shouldn't we also already include an API to return all tuples [action agenda ID, action agenda name]? otherwise we must guess, thus the GET /actionagenda/{aaId} we offer is not usable
• For all the objects we return, I think we must include their PK identifier. (so, aaId, faId, aID, iId, or AAid, FAid, Aid, Iid) (granted, we can add this to the contract at the next update, but since we're allowed BC now before launching the product, it's fine to include them now). If we want to change an indicator, we'll need to know its PK in the DB, because that's the only way we can manipulate them.

[HassanCehef]

Suggested change

	example: 5
	example: 5

empty line at the end of file

[HassanCehef]

Suggested change

	description: For valid response try integer IDs with value >= 1 and <= 10. Other
	values will generated exceptions
	description: >
	Get one Action Agenda by ID

?

[HassanCehef]

Suggested change

	components:
	components:

I like line breaks

[HassanCehef]

Suggested change

	content: {}
	content: {}
	default:
	description: Error

This fixes the 401 request by Rik. I don't think we need to specify here the meaning of 401, because the whole API is only accessible with authN

[HassanCehef]

Suggested change

	properties:
	required:
	- name
	- minimum
	- maximum
	properties:

[HassanCehef]

Suggested change

	properties:
	required:
	- name
	- actions
	properties:

[HassanCehef]

Suggested change

	FocusArea:
	FocusArea:

[HassanCehef]

Suggested change

	Action:
	Action:

[HassanCehef]

Suggested change

	Indicator:
	Indicator:

[HassanCehef]

When we return an ActionAgenda, we must also return its ID, because that's the only way we can manipulate this object.