Ensure correct request / response format

[heggert]

The REST-API interfaces of the framework services do not always correspond to our standard specifications regarding the request/response format.

1. The request JSON body format for GET / POST / PATCH / PUT / DELETE should not contain the "data" property. Examples that conform to this specification:

Request POST api/service/resource/
body (application/json)

{
	"property1": "1",
	"property2": "abc"
	...
}

Request PATCH api/service/resource/:id
body (application/json)

{
	"property3": "1"
}

2. The response JSON body format must contain at least the "data" property and should contain the "meta" property. Examples that conform to this specification:

Response GET api/service/resource
body (application/json)

{
	"data": [
		{
			"property1": "1",
			"property2": "abc"
		},
		{
			"property1": "2",
			"property2": "abc"
		}
	],
	"meta": {
        	"page": 1,
        	"perPage": 2,
        	"total": 2,
    		"totalPages": 1
	}
}

Response GET api/service/resource/123
body (application/json)

{
	"data": {
		"property1": "123",
		"property2": "abc"
	}
}

All framework services within /services must be examined and, if necessary, adjusted. Communication between the services within the framework must not be impaired.

• app-directory
• attachment-storage-service
• audit-log
• component-orchestrator
• component-repository
• data-hub
• dispatcher-service
• flow-repository
• iam
• ils
• meta-data-repository
• reports-analytics
• scheduler
• secret-service
• snapshots-service
• template-repository
• webhooks

[weberjm]

Good description, thanks! The JSON API spec also has some background on the need for the data field, and I think makes for a good review.

I agree with you, though, that the data field is generally not required for the Request object, as you will never make a request with an errors or meta object.

[SvenHoeffler]

After a preliminary examination, it fortunately looks like the majority of services already adhere to the schema. The exceptions I have found so far are as follows:

• App Directory: Get Response does not contain data/meta
• Component Repository: Request body requires superfluous data key
• IAM: Get Responses do not contain data/meta
• Secret Service: Request bodies requires superfluous data key
• Webhook Service: Request bodies requires superfluous body key (this is related to Enable passing webhook data into a flow #1201), response body does not have data/meta (less of an issue as webhook service cannot return meaningful data)