[midPoint] Development of the REST API

[Beat Rohrer]

>> One of the reason why I've called it a "thin wrapper" is, because the 
>> XML seems to take precedence over anything I've provided in the URI. 
>> E.g. I've POSTed to http://localhost:8080/midpoint/ws/rest/users/ XML 
>> data of a new user which accidentally contained the oid of an 
>> existing user in the root element. I would expect the API to respond 
>> with an error, but it has just updated the existing user (and 
>> responded with "201 Created").
>
> Yes, you are right. That is a bug. Feel free to file that bug in our 
> jira: https://wiki.evolveum.com/display/midPoint/Creating+a+Bug+Report

I have a feature request for the bug report form: ;-)

I can't find a decent "Component" category for an API bug, it doesn't 
seem to fit anywhere. Couldn't you make a category for "API"?

>> - respond with an error code and a message
>
> Agreed. But the problem is that a short message is often not enough to 
> diagnose a problem. E.g. there might be errors inside an operation, 
> some of the error might be handled, other not, part of the operation 
> was a success and other parts not. As midPoint is using connectors and 
> it communicates with a number of external and really unpredictable 
> systems, midPoint does not always understands what exactly is going on 
> and what's the problem. I cannot really imagine to have a numeric code 
> for every possible error condition in midPoint. Simplistic 
> twitter-like approach will be a step in a good direction and it can be 
> used to divide errors into classes (roughly by existing exception and 
> SOAP fault classes that we already have). It is a good start, but it 
> is not really enough.
>
> We have a partial error and handled error status code for individual 
> operations. As far as I know there is no equivalent in HTTP for that. 
> We have a rich data structure (OperationResult) that is a hierarchical 
> and can describe what exactly was tried and what exactly went wrong. 
> We are placing that in the SOAP faults so a SOAP client can take a 
> full advantage of that. But I have no idea how to do similar thing in 
> RESTful service without turning the service into RPC. Any ideas?
>>   - PATCHes should be much simpler: why do I have to reference 
>> objectType, changeType, oid, and itemDelta? When I'm sending a PATCH 
>> to /{type}/{oid} this is already defined and the diff should be 
>> enough
>
> The delta is our diff. Yes, objectType and OID should not be there 
> because that is already in the URI. And the changeType is implicit in 
> this case. You are right, these are mostly leftover from the Java and 
> SOAP operations. To keep things simple we have decided to reuse the 
> same data structures and forgot to clean it up later. That can be 
> improved.
>
> But we need item deltas. We cannot remove these. Or is there any 
> representation-agnostic way how to describe a fine-grained change 
> inside the web resource? I'm not aware of any.

I've forwarded these two questions to our development team's REST-nerd, 
he will hopefully come up with a good answer for me to relay to you ;)

> Thanks for your suggestions, they are most welcome. Maybe you could 
> create an "improvement" issue in our jira and summarize the suggested 
> improvements there?

Ok, I'll do that.

> Most of the suggestions can be implemented quite quickly. However, 
> this will need an endorsement from a midPoint subscriber to fit it 
> into the roadmap: https://wiki.evolveum.com/display/midPoint/Roadmap

I totally understand that. If we decide to deploy midPoint at our 
university, I'll advocate to sponsor the development ourselves.

Thank you very much for your thoughtful answers

Beat