Comments (5)
Would you be up for taking a first pass at this? It could probably fit in the Requests
section and be structured similar to the status codes stuff in Responses
(ie a bulleted list). I'm happy to take it from there and flesh it out, but would definitely welcome contribution as well. Thanks!
from http-api-design.
@geemus I had a look at the heroku platform API and noticed that you're supporting the wide-spread (wrong?) use of PATCH as a partial resource update action, instead of how it's described in RFC 5789
with PATCH, however, the enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version.
Is this deliberate? And if so, why? Or am I misinterpreting the spec?
from http-api-design.
Of course only seconds after posting I found this: http://tools.ietf.org/html/draft-ietf-appsawg-json-patch-10
A spec on how to describe PATCH operations through JSON API's. E.g.:
{ "op": "replace", "path": "/a/b/c", "value": 42 }
The path
key is maybe a bit ill chosen, it
references a location within the target document
Anyway, converting an example from the heroku docs would make it:
$ curl -n -X PATCH https://api.heroku.com/account \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d '{
"op": "replace", "path": "email", "value": "[email protected]"
}'
from http-api-design.
And sorry for hijacking this thread, but come to think of it, this would mean the actions
part could be described entirely using PATCH instead.
from http-api-design.
@creynders - I can certainly see what you are getting at. In our case, we just wanted partial update. ie we simplify the usage a bit through the assumption that you ALWAYS want to do replace ops and you are just specifying key/value. I think this is still in the spirit of the RFC, though one could argue we should be using a special media type that better defines these expectations. ie we just have a much simpler/more naive patch document format than say json-patch.
I don't think this would be sufficient to accomodate actions
as those are more likely to be things like start
/stop
/transfer
, etc. ie things that are more complex than modifying a particular attribute value, which I think is the scope of capability afforded to json-patch.
Hope that helps clarify a bit, but certainly happy to further discuss.
from http-api-design.
Related Issues (20)
- uuid in doubt HOT 4
- Dead link in about section HOT 1
- Guidance on implementing REST interfaces for state machine HOT 21
- I'm curious to know the reasoning for going with JSON Schemas instead of Swagger HOT 5
- How are you modeling authentication operation? HOT 1
- Using 409 Conflict for uniqueness checks HOT 2
- Create a website (Gitpage) HOT 3
- Traditional Chinese version, and add "List of Translations" HOT 5
- Consider adding language specific resources for implementing these principles HOT 1
- consider expanding error messaging as per white house guide HOT 7
- include more examples for main points HOT 9
- detail expansions
- Consider compatibility with jsonapi.org? HOT 8
- Why use UUID? HOT 12
- Paginating/ranging over non-unique fields HOT 15
- Pagination using Range cannot be consistent HOT 8
- Test Framework HOT 1
- The used time format is actually RFC5424, a subset of ISO8601 HOT 2
- Json with PLSQL ( PLJSON) HOT 1
- Links in README.md are 404 when viewed on Gitbook HOT 5
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from http-api-design.