[midPoint] Development of the REST API

[Beat Rohrer]

Hi Radovan,

Thank you for your response.

> In fact the RESTful interface is very stable for several releases 
> already. Currently we do not plan any big changes and we definitely do 
> not plan any incompatible change in any midPoint interfaces in the 
> next year or two.
>
> So, just the wiki page was out of date. I have edited the wiki page to 
> reflect current state.

thanks

> In fact, the REST interface should be OK for production use. Both REST 
> and SOAP services are based on the same underlying interface 
> (https://wiki.evolveum.com/display/midPoint/IDM+Model+Interface) 
> that's the reason why REST service is similar to SOAP. But it is a 
> proper resource-oriented service. Even our SOAP interface has some 
> REST-like character because that's the way how the underlying Java API 
> is designed (object-oriented CRUD-like mechanism).

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").

Also, you wouldn't expect to *POST* to a sub-resource /{type}/search in 
order to GET the data…

> So the REST service is stable and mostly feature-complete. One thing 
> than I'm aware which is missing from REST is the comprehensive 
> executeChanges() operation that is available in SOAP and Java 
> interfaces. The reason that this operation is missing is that there is 
> no clean RESTful way how to make operations on several web resources 
> in one invocation. This is a inherent limitation of RESTful approach. 
> However there are usual RESTful modification operations that can be 
> used per web resource and that is almost equivalent for most cases.
>
> But you might be right when it comes to a useful feedback from the 
> REST operations. We have been struggling a bit with this. In SOAP 
> there is a standard concept of SOAP Fault and we are using that. But 
> I'm not aware of any good way how to do similar thing in RESTful 
> service. As far as I know we are trying to properly return HTTP 
> response codes. But is there anything more that we can do? Some kind 
> of standard or a widely accepted convention for REST services? I would 
> really like to know. We have a very good structured diagnostic info 
> for each operation. We just need a way how to expose that in a RESTful 
> way.

I'd propose the following improvements:

- always respond in the requested format: if the request says "Accept: 
application/xml", please respond in application/xml and not in HTML
- don't respond with an error 500 if my request actually is the problem, 
e.g. when referencing an non-existing role oid in a create user POST
- respond with an error code and a message

You could have a look at twitter's API for their error handling: 
https://dev.twitter.com/overview/api/response-codes

> We do not have a specific roadmap for the development of RESTful 
> service yet. But maybe we can do that. Can you please be a bit more 
> specific about the things that you would like to see in the REST 
> interface?

Additionally to the things mentioned above:

- please implement JSON
- I'd really like to see an abstraction layer between the internal 
interface and the API, i.e.:
   - xmlns references should not be part of the REST interface
   - 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
   - implement search as URI attributes with GET
- I'd expect to receive a list of all resources of a type, when GETting 
/{type}/
- please improve the REST API's documentation: in the current state, 
there is no way to understand the XML structure just from reading the 
doc and the referenced resources; e.g. please link the resources to 
their respective class documentation, provide a link to the search query 
format etc.

Thank you for your time

Beat