create-form / edit-form: The "create-form" and "edit-form" Link Relations
Two standard link names for web forms that create or edit resources.
Dzmanashvili, I., "The "create-form" and "edit-form" Link Relations", RFC 6861, DOI 10.17487/RFC6861, January 2013, <https://www.rfc-editor.org/info/rfc6861>.
@misc{rfc6861,
series = {Request for Comments},
number = 6861,
howpublished = {RFC 6861},
publisher = {RFC Editor},
doi = {10.17487/RFC6861},
url = {https://www.rfc-editor.org/info/rfc6861},
author = {I. Dzmanashvili},
title = {{The "create-form" and "edit-form" Link Relations}},
pagetotal = 6,
year = 2013,
month = jan,
} RFC text
Contents
Independent Submission I. Dzmanashvili
Request for Comments: 6861 January 2013
Category: Informational
ISSN: 2070-1721
The "create-form" and "edit-form" Link Relations
Abstract
RFC 5988 standardized a means of indicating the relationships between
resources on the Web. This specification defines link relation types
that may be used to express the relationships between a resource and
an input form for constructing data submissions.
Status of This Memo
This document is not an Internet Standards Track specification; it is
published for informational purposes.
This is a contribution to the RFC Series, independently of any other
RFC stream. The RFC Editor has chosen to publish this document at
its discretion and makes no statement about its value for
implementation or deployment. Documents approved for publication by
the RFC Editor are not a candidate for any level of Internet
Standard; see Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc6861.
Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document.
Table of Contents
1. Introduction ....................................................2
2. Notational Conventions ..........................................2
3. Link Relations ..................................................3
3.1. The "create-form" Link Relation Type .......................3
3.1.1. Using the "create-form" Link Relation ...............3
3.2. The "edit-form" Link Relation Type .........................3
3.2.1. Using the "edit-form" Link Relation .................4
3.3. Error-Handling Example .....................................4
4. IANA Considerations .............................................4
4.1. The Link Relation Registration "create-form" ...............4
4.2. The Link Relation Registration "edit-form" .................5
5. Security Considerations .........................................5
6. Internationalisation Considerations .............................5
7. Normative References ............................................5
Appendix A. Acknowledgements .......................................6
1. Introduction
RFC 5988 [RFC5988] standardized a means of indicating the
relationships between resources on the Web. This specification
defines link relation types that may be used to express the
relationships between a resource and an input form for constructing
data submissions.
The "create-form" and "edit-form" link relations are intentionally
generic, and they can be used with multiple media types in a wide
variety of use cases.
2. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
3. Link Relations
The following link relations are defined.
3.1. The "create-form" Link Relation Type
When included in a response, the "create-form" link relation
indicates a target resource that represents a form that can be used
to append a new member to the link context.
<html>
<ul>
<li>Entry Description 1</li>
<li>Entry Description 2</li>
</ul>
<a href="..." rel="create-form">[Add New Entry]</a>
</html>
or, expressed as a Link header
Link: <...>; rel="create-form"; title="Add New Entry"
3.1.1. Using the "create-form" Link Relation
If the form representation includes a submission URI, this URI MUST
be used to submit the form. The context URI SHOULD be used
otherwise.
If the form representation includes a submission method, this method
MUST be used for submit requests. HTTP's POST method SHOULD be used
otherwise.
3.2. The "edit-form" Link Relation Type
When included in a response, the "edit-form" link relation indicates
a target resource that represents a form that can be used for
updating the context resource.
<html>
...
<ul>
<li>
Entry Description 1
<a href="..." rel="edit-form">[Edit Entry]</a>
</li>
</ul>
...
</html>
or, expressed as a Link header
Link: <...>; rel="edit-form"; title="Edit Entry"
3.2.1. Using the "edit-form" Link Relation
If the form representation includes a submission URI, this URI MUST
be used to submit the form. The context URI SHOULD be used
otherwise.
If the form representation includes a submission method, this method
MUST be used for submit requests. HTTP's PUT method SHOULD be used
otherwise.
3.3. Error-Handling Example
When submitting forms in unsupported media type format, service may
respond to the client with HTTP's 415 Unsupported Media Type status
code.
HTTP/1.1 415 Unsupported Media Type
Link: <...>; rel="create-form"; title="Create new entry"
Content-Type: text/html
Content-Length: ...
<html>
Use <a href="..." rel="create-form">
this form
</a> to create a new entry.
</html>
4. IANA Considerations
IANA has registered the "create-form" and "edit-form" link relations
below as per [RFC5988].
4.1. The Link Relation Registration "create-form"
Relation Name:
create-form
Description:
The target IRI points to a resource where a submission form can be
obtained.
Security considerations:
Automated agents should take care when this relation crosses
administrative domains (e.g., the URI has a different authority
than the current document).
Reference:
See Section 3.
4.2. The Link Relation Registration "edit-form"
Relation Name:
edit-form
Description:
The target IRI points to a resource where a submission form for
editing the associated resource can be obtained.
Security Considerations:
Automated agents should take care when this relation crosses
administrative domains (e.g., the URI has a different authority
than the current document).
Reference:
See Section 3.
5. Security Considerations
See Section 7 of RFC 5988 [RFC5988].
6. Internationalisation Considerations
See Section 8 of RFC 5988 [RFC5988].
7. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
Appendix A. Acknowledgements
The author gratefully acknowledges the contributions of Jan
Algermissen.
Author's Address
Ioseb Dzmanashvili
EMail: ioseb.dzmanashvili@gmail.com
AI ELI5
On this page
§1Web Linking and Link Relations
RFC 5988 standardized the concept of link relations, which describe the relationship between resources on the web. A link relation tells a client what a linked resource represents. For example, a rel="alternate" link means the target is an alternate version of the current resource; rel="next" means the next item in a sequence.
This RFC defines two new link relation types for a common use case: forms. When a web resource wants to let clients know where to find a form for creating or editing data, it can use the standard `create-form` or `edit-form` relation to advertise the form's location. Without a standard, every API uses different conventions, making it hard for generic clients to find forms automatically.
Web links have names describing what they point to. This document adds two new standard names: one for a form that creates a new thing, and one for a form that edits something.
§2The Two Link Relations
The create-form link relation indicates a resource that is a form for adding a new member to a collection. When a client follows a create-form link, it receives a form that it can fill out and submit to create a new entry.
The edit-form link relation indicates a resource that is a form for updating an existing resource. A client can use this form to modify the current resource.
A server can advertise these links in two ways. In HTML, using the <a> tag with rel="create-form" or rel="edit-form". Alternatively, in a Link HTTP header:
Link: </forms/entry>; rel="create-form"; title="Add New Entry"
The links can include optional attributes like title to describe the form to users.
Create-form points to a form for making a new entry. Edit-form points to a form for changing an existing one. Servers list these links like directions.
<html>
<ul>
<li>Item 1 <a href="/edit/1" rel="edit-form">[Edit]</a></li>
<li>Item 2</li>
</ul>
<a href="/create" rel="create-form">[Add New Item]</a>
</html>
Link: </create>; rel="create-form"; title="Add New Entry"
Link: </edit/1>; rel="edit-form"; title="Edit Entry"§3How to Use These Relations
When a client gets a form through a create-form or edit-form link, the form representation itself may specify where to submit and how.
For create-form: If the form includes a submission URI, that URI MUST be used. Otherwise, the client SHOULD use the URI of the current resource. If the form specifies an HTTP method, that method MUST be used. Otherwise, clients SHOULD use POST.
For edit-form: If the form includes a submission URI, that URI MUST be used. Otherwise, the client SHOULD use the URI of the current resource. If the form specifies an HTTP method, that method MUST be used. Otherwise, clients SHOULD use PUT.
These relations are intentionally generic and can be used with multiple media types and in a wide variety of use cases. A server can even return a create-form link in an error response, for example when the client submits data in an unsupported format.
The form tells you where to send it and what HTTP command to use. If it doesn't, use POST for creating and PUT for editing. It works with any kind of web data.
§4Registration and Status
RFC 6861 registers both link relation types with IANA (the Internet Assigned Numbers Authority) according to the procedures in RFC 5988. This ensures the names are officially recognized and documented.
Both relations are generic and can be used in any context where a form is needed for creating or editing. Automated agents and clients should be aware that following these links might take them to resources in different administrative domains (different websites or authorities), and they should apply appropriate security measures.
RFC 6861 is informational and has not been obsoleted. The link relations are now standards for web linking.
These link names are officially registered, so everyone uses the same standard names. Be careful if a link takes you to a different website.