1

When a client requests my .../resources/user URL with a HTTP GET I get the following response:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<collection>
    <User id="5">
        <Password>DC647EB65E6711E155375218212B3964</Password>
        <FirstName>Super</FirstName>
        <LastName>Admin</LastName>
        <Role id="4">
            <Description>Default Guest Role</Description>
            <Group id="2">
                <Description>Default Guest Group</Description>
                <Name>GuestGroup</Name>
            </Group>
            <Name>Guest</Name>
        </Role>
        <Role id="3">
            <Description>Default Super Admin Role</Description>
            <Group id="1">
                <Description>Default Admin Group</Description>
                <Name>AdminGroup</Name>
            </Group>
            <Name>SuperAdmin</Name>
        </Role>
        <Username>superadmin</Username>
    </User>
    <User id="6">
        <Password>DC647EB65E6711E155375218212B3964</Password>
        <FirstName/>
        <LastName>Guest</LastName>
        <Role id="4">
            <Description>Default Guest Role</Description>
            <Group id="2">
                <Description>Default Guest Group</Description>
                <Name>GuestGroup</Name>
            </Group>
            <Name>Guest</Name>
        </Role>
        <Username>guest</Username>
    </User>
</collection>

For data transport efficiency purposes I would also like the client to be able to request a short version of this response. Something like:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<collection>
    <User id="5">
        <Password>DC647EB65E6711E155375218212B3964</Password>
        <FirstName>Super</FirstName>
        <LastName>Admin</LastName>
        <Role id="4" />
        <Role id="3" />
        <Username>superadmin</Username>
    </User>
    <User id="6">
        <Password>DC647EB65E6711E155375218212B3964</Password>
        <FirstName/>
        <LastName>Guest</LastName>
        <Role id="4" />
        <Username>guest</Username>
    </User>
</collection>

What is the best way to identify a full and a short request from the client and why? Client technology should be agnostic. Server technology is Java EE 7

A few options I thought of myself:

  • Sub level webservices like .../resources/user/short
  • Different webservices like .../resources/user2
  • Use a custom HTTP parameter lik Accept-Length : Short
  • Use the HTTP request field Expect : Short
9
  • 1
    Too opinion based for an answer, but I would probably go for a query parameter: /resources/user?format=full(default) or /resources/user?format=short. Or provide only the short format, with links for the embedded Role resources. Jan 20 '15 at 17:42
  • 1
    Query parameter sounds right. You could model it after JIRA's API, they call it expansion. Honoring a JSON Content-Type header would shave some bytes off too.
    – Hey
    Jan 20 '15 at 18:42
  • 1
    I would avoid returning a password hash via API. Another potential issue is that your hash looks unsalted. Password hashes should be slow and salted. Jan 20 '15 at 19:56
  • Thanks @Hey for pointing me to the JIRA api solution. Perfect choice in my opinion. Jan 20 '15 at 20:24
  • 1
    Because the query strings are designed for filtering resources rather than specifying the format of the resource. Content-Type specifies the form to return the resource in. Saying I want it in short form is no different to saying I want it in JSON instead of default HTML or saying give me a picture in PNG rather than JPEG. It is a formatting issue which is what Content Type was designed for. Jan 23 '15 at 16:04
0

My view is that the client is requesting a different representation of the resource i.e. a short one.

When you request a different representation (like json or xml) this normally gets tagged at the end of the resource e.g. /some/resource.json, /some/resource.xml

So you could take the same logic and do something like /some/resource.short.json

1

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.