From 1a0b4f96fecbbdaea5c741351239846df50e2900 Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Mon, 6 Jun 2016 20:19:00 -0400 Subject: [PATCH] Added draft RFC for Read/Write Attributes --- rfcs/read-write.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 rfcs/read-write.md diff --git a/rfcs/read-write.md b/rfcs/read-write.md new file mode 100644 index 0000000..1ae9b04 --- /dev/null +++ b/rfcs/read-write.md @@ -0,0 +1,52 @@ +--- +RFC: XXXX +Author: Phil Sturgeon +Status: Draft +Created: 2016-06-06 +Last Modified: 2016-06-06 +--- + +# API Blueprint RFC XXXX: Readable & Writable Attributes + +## Table of Contents + +- [Abstract](#abstract) +- [Motivation](#motivation) +- [Rationale](#rationale) +- [Backwards Compatibility](#backwards-compatibility) + +## Abstract + +This RFC proposes the addition of keywords `readable` and `writable`, to mark +if a particular attribute is read-only, write-only, or by default: both. + +In a very similar fashion to `required` and `optional`, these options would go +into the attribute definition: + +``` md ++ created: 1415203908 (number, readable) - Time stamp +``` + +For this example, `created` is a server-generated field which will not come +from the client, and trying to set it could either do nothing (ignoring the +value) or error, entirely at the will of the server implementation. + +## Motivation + +Whilst attributes in resources should be as close to identical on write and read +as possible, they are often not. Sometimes attributes will be displayed, but +if you try to modify them in a `POST`, `PUT` or `PATCH` they will be ignored. + +Sometimes a value might be available to write, but will not be presented back to +the client in a `GET` action, or in the response body. This is more rare for +REST APIs, but it does still happen. + +Communicating when fields are read-only or write-only in the existing +documentation structure can be difficult. + +Clients can end up sending fields which are not being saved, and if the server +is not so strict as to error, it will simply be black-holing that data. + +## Backwards Compatibility + +No breaks here, it just adds another pair of words to the list.