Question

Let’s say I have an object, Widget, comprised of an Id and a Name. Let’s say I expose an endpoint, /widget, where clients can POST new Widget objects. If I want the Id field to always be set by the server, not modifiable by the client, but still visible to clients, how can I declare that the Id field is not modifiable? I’m using RESTeasy if that makes any difference.

Answer 1

I can think of a few options.

First, are you sure you need to expose the ID as part of the representation? Or is it enough to respond with the location of the new posted resource?

Your client posts:

<Resource><Name>New Resource</Name></Resource>

And you respond:

HTTP/1.1 201 Created
...
Location: /resources/{new_resource_id}

Beyond that, I think it’s OK to have some simple, well-understood conventions with your clients. I think most developers understand that an ID is likely to be system-generated (especially, since you’re doing a POST and not a PUT). For less obvious cases, where you have arbitrary read-only fields (or other validation or display information), I think it may make sense to provide a link to metadata:

<NewPersonForm>
    <atom:link href="/people/new/metadata" rel="/rels/metadata" />
    <Name />
    <Department>HR</Department>
</NewPersonForm>

What the metadata looks like is up to you, but something along these lines might work for you:

<Metadata>
    <Element>
        <Name>Department</Name>
        <IsReadOnly>True</IsReadOnly>
    </Element>
</Metadata>

That’s a nice, format-neutral (it works well for both XML and JSON) way to provide information to the client, and if they really want to, they can program against it to build forms on the fly (I use it to provide validation information, language-specific labels, and data type information).

I hope this helps.

John