19

there been quite good thread on rest urls in SO.

Is this a bad REST URL? Understanding REST: Verbs, error codes, and authentication

I see a good resource here as well.

The question is how to represent the create and edit forms urls. The So links doesn't clearly say that, but the microformats links suggest

GET /people/new

return a form for creating a new record

GET /people/1/edit

return a form to edit the first record

Not being too religious about using verbs in url, wonder whether there a better option to represent the same.

Community
  • 1
  • 1
bsr
  • 57,282
  • 86
  • 216
  • 316

2 Answers2

17

The reason that you will find no consensus on the structure of the URL is because when developers start to understand REST they learn that the structure is irrelevant to the client and is simply a function of aesthetics and server framework implementations.

However, there is a standardized approach to achieving the goals you are trying to achieve.

GET /people/1
Content-Type: application/vnd.hal+xml
=>
<resource rel="self" href="/people/1">
  <link rel="edit" href="/people/1/editform"/>
  <link rel="urn://vnd.acme.rels/create" href="/people/createform"/>
  <name>Joe Foo</name>
</resource>

By embedding links into the response the client can discover the URI needed to perform the desired action. However, to discover the URI, the client needs to have prior knowledge of the link relations ("rel") that are being used. In this case we used "edit" as that has a well defined behaviour described in the IANA Link Registry. The other link for accessing a create form, as far as I know, does not have a standard name, so I took the liberty of creating a uniquely named link relation.

As a side note, I happened to use the media type application/hal+xml because it is a flexible hypermedia format but is simple enough to understand without reading too much documentation.

Darrel Miller
  • 139,164
  • 32
  • 194
  • 243
  • +1 for `rel="edit"` and the IANA Link Registry: I knew of neither. However, it is unfortunately not an HTML5 link relation: http://www.w3.org/TR/2011/WD-html5-20110525/links.html#linkTypes – Raedwald Aug 28 '12 at 22:17
  • @Raedwald Don't worry. Link relations are independent of media types. HTML just included the ones they minted. You can use any others. There is another registry here http://microformats.org/wiki/existing-rel-values – Darrel Miller Aug 29 '12 at 12:30
  • Returning the link for creating a person when viewing a person doesn't make sense. You should get the create form link when doing a GET on /people not on /people/1. You say that link structure is irrelevant but not being able to discover the link to make a person unless there is a person is bad design. The new player form isn't part of the player resource so it probably makes more sense to include the link to the form as a [Link header](http://www.w3.org/Protocols/9707-link-header.html). `Link: ; rel="new"` instead as part of the representation of all the people. – Chase Mar 11 '13 at 22:00
  • @Chase There are lots of UIs out there that allow you to add a new `foo` whilst looking at an existing `foo`. If I designed resources based on some kind of domain model then you would probably be correct. However, I don't, my resources reflect my application workflow. I would most likely have a create link within my `/people` resource also. – Darrel Miller Mar 11 '13 at 22:27
  • also, it is a common pattern where `GET /people` returns a list of all people entities (no-filter). This makes more semantic sense than returning a form. – cowbert Mar 14 '18 at 01:10
8

There's an informational RFC recently published that promotes the link relations "create-form" and "edit-form". More information can be located at https://www.rfc-editor.org/rfc/rfc6861.

Community
  • 1
  • 1
Josh Ferguson
  • 81
  • 1
  • 1
  • So what's the difference between `edit` and `edit-form`? Why was `edit-form` introduced in the first place if we already have `edit`? (I must be missing something) – mb21 Feb 27 '16 at 09:47