How to represent a read-only property in a REST Api

Question

if you have a REST API that is hypermedia-driven (HATEOAS) you can easily change a client's behavior by including or omitting links in the response (_links). That enables a client to completely forget about testing permissions for the operations that are possible in the current state of a resource (the link to the operation is present or not).

Additionally you can leave out properties in the response if the current user doesn't have permission to see it.

That way authorization is done entirely on the server (and controls actions and properties that are eligible to execute/view).

But what if I want to a have a read-only property? It is no problem for the REST API to ignore the property if it is present in the request (_POST_ OR _PUT_). it just won't get saved. But how can a client distinguish between write and read-only properties to present the user appropriate controls (like a disabled input field in HTML)?

The goal is to never ever have the client request a user's permissions, but to have a completely resource driven client/frontend.

Any help is greatly appreciated :-)

Loughlin

As your response is probably based on some document format (XML and JSON are rather generic; more specialized ones are preferable and extending one isn't that hard), use some schemas which describe your document format to define what is compulsory, what optional and what is read-only – Jana

ok I seet what you mean, but I mean a property that is either writeable, readonly, or not present depending on the user's permissions. So the schema would be dynamic – Loughlin

I would leave the checks on the server side and return a specialized document format for certain roles. Here the schema of the document format contains the necessary information if a property is read only, optional or compulsory for eventual client responses. Note, the document format for different roles need not be identical. It can either be a subset, superset or something totally different in comparison to some base-role. – Jana

Answer 1

If I misunderstood your question, I apologize upfront. With that being said...

But how can a client distinguish between write and read-only properties to present the user appropriate controls (like a disabled input field in HTML)

Well, there are multiple solutions to this. The simplest one I can personally think of is to make each property an object having a simple structure of something like:

    ...

    someProperty: {
        value: 'some value',
        access: 'read-only'
    },
    someOtherProperty: {
        value: 'some value',
        access: 'write'
    }
    ...

You can obviously get as creative as you want with how you represent the "access" level of the property (using enums, booleans, changing access to be isReadOnly or whatever).

After that, the person using the API now knows they are read-only or not. If they submit a "write" value for a "read-only" property as part of the POST payload, then they should expect nothing less than a 403 response.

Edit: In case you can't alter the properties in this manner, there are a number of other ways you can still achieve this:

• write documentation that explains what access each property has
• create a route that the user can submit 1 or more properties to in order to receive a response that indicates the access level of each property (response: { propName: 'read-only', propName2: 'write', etc.)
• Return a propertyAccess map as part of the response (mapping properties to access levels).

end of the day, you just need a way to map a property with an access level. however that's done depends on what your restrictions and requirements are for the api, what changes you can make, and what is acceptable to both your client(s) and the business requirements.

Moldboard

you're right, I thought there must have been an easy way to accomplish this without adding too much meta-information to the response. Maybe I'll come up with a more satisfying solution. If that happens, I will post it here. In the meantime I going to mark your answer as accepted! – Loughlin

rock on! please do post though - it will be interesting to see what you came up with. – Moldboard