From a96211d3d1ba246512af5e32c31726a666c467ac Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sun, 16 Sep 2012 21:48:55 +0100 Subject: Simplify negotiation. Drop MSIE hacks. Etc. --- docs/topics/rest-hypermedia-hateoas.md | 52 ++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 docs/topics/rest-hypermedia-hateoas.md (limited to 'docs/topics/rest-hypermedia-hateoas.md') diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md new file mode 100644 index 00000000..2bca2ab8 --- /dev/null +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -0,0 +1,52 @@ +> You keep using that word "REST". I do not think it means what you think it means. +> +> — Mike Amundsen, [talking at REST fest 2012][cite]. + +# REST, Hypermedia & HATEOAS + +First off, the disclaimer. The name "Django REST framework" was choosen with a view to making sure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs". + +If you are serious about designing a Hypermedia APIs, you should look to resources outside of this documentation to help inform your design choices. + +The following fall into the "required reading" category. + +* Fielding's dissertation - [Architectural Styles and +the Design of Network-based Software Architectures][dissertation]. +* Fielding's "[REST APIs must be hypertext-driven][hypertext-driven]" blog post. +* Leonard Richardson & Sam Ruby's [RESTful Web Services][restful-web-services]. +* Mike Amundsen's [Building Hypermedia APIs with HTML5 and Node][building-hypermedia-apis]. +* Steve Klabnik's [Designing Hypermedia APIs][designing-hypermedia-apis]. +* The [Richardson Maturity Model][maturitymodel]. + +For a more thorough background, check out Klabnik's [Hypermedia API reading list][readinglist]. + +# Building Hypermedia APIs with REST framework + +REST framework is an agnositic Web API toolkit. It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style. + +### What REST framework *does* provide. + +It is self evident that REST framework makes it possible to build Hypermedia APIs. The browseable API that it offers is built on HTML - the hypermedia language of the web. + +REST framework also includes [serialization] and [parser]/[renderer] components that make it easy to build appropriate media types, [hyperlinked relations][fields] for building well-connected systems, and great support for [content negotiation][conneg]. + +### What REST framework *doesn't* provide. + +What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] by default, or the ability to auto-magically create HATEOAS style APIs. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. + +[cite]: http://vimeo.com/channels/restfest/page:2 +[dissertation]: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm +[hypertext-driven]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven +[restful-web-services]: +[building-hypermedia-apis]: … +[designing-hypermedia-apis]: http://designinghypermediaapis.com/ +[restisover]: http://blog.steveklabnik.com/posts/2012-02-23-rest-is-over +[readinglist]: http://blog.steveklabnik.com/posts/2012-02-27-hypermedia-api-reading-list +[maturitymodel]: http://martinfowler.com/articles/richardsonMaturityModel.html + +[collection]: http://www.amundsen.com/media-types/collection/ +[serialization]: ../api-guide/serializers.md +[parser]: ../api-guide/parsers.md +[renderer]: ../api-guide/renderers.md +[fields]: ../api-guide/fields.md +[conneg]: ../api-guide/content-negotiation.md \ No newline at end of file -- cgit v1.2.3 From 308677037f1b1f2edbd2527beac8505033c98bdc Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 17 Sep 2012 20:19:45 +0100 Subject: Tweak docs, fix .error_data -> .errors --- docs/topics/rest-hypermedia-hateoas.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/topics/rest-hypermedia-hateoas.md') diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index 2bca2ab8..46a4c9d7 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -1,8 +1,8 @@ +# REST, Hypermedia & HATEOAS + > You keep using that word "REST". I do not think it means what you think it means. > -> — Mike Amundsen, [talking at REST fest 2012][cite]. - -# REST, Hypermedia & HATEOAS +> — Mike Amundsen, [REST fest 2012 keynote][cite]. First off, the disclaimer. The name "Django REST framework" was choosen with a view to making sure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs". -- cgit v1.2.3 From f4d4d54e030addf64efe68f387b934262a3c173b Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 8 Oct 2012 12:17:43 +0100 Subject: Adding migration and changelog docs --- docs/topics/rest-hypermedia-hateoas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/topics/rest-hypermedia-hateoas.md') diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index 46a4c9d7..3aa1ff5f 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -20,7 +20,7 @@ the Design of Network-based Software Architectures][dissertation]. For a more thorough background, check out Klabnik's [Hypermedia API reading list][readinglist]. -# Building Hypermedia APIs with REST framework +## Building Hypermedia APIs with REST framework REST framework is an agnositic Web API toolkit. It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style. -- cgit v1.2.3 From 65f592866c5cd5103e99ed453543807bcbdaa9da Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 8 Oct 2012 17:53:18 +0100 Subject: Fix issue where required fields were not being properly validated. Also make model fields with a default value be not required --- docs/topics/rest-hypermedia-hateoas.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/topics/rest-hypermedia-hateoas.md') diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index 3aa1ff5f..0e183a49 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -32,7 +32,7 @@ REST framework also includes [serialization] and [parser]/[renderer] components ### What REST framework *doesn't* provide. -What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] by default, or the ability to auto-magically create HATEOAS style APIs. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. +What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] or HTML [microformats] by default, or the ability to auto-magically create HATEOAS style APIs. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. [cite]: http://vimeo.com/channels/restfest/page:2 [dissertation]: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm @@ -45,6 +45,7 @@ What REST framework doesn't do is give you is machine readable hypermedia format [maturitymodel]: http://martinfowler.com/articles/richardsonMaturityModel.html [collection]: http://www.amundsen.com/media-types/collection/ +[microformats]: http://microformats.org/wiki/Main_Page [serialization]: ../api-guide/serializers.md [parser]: ../api-guide/parsers.md [renderer]: ../api-guide/renderers.md -- cgit v1.2.3 From 52a2ff8f77dc22a65e6f5780de8183f261472342 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 9 Oct 2012 16:44:49 +0100 Subject: Docs tweaks --- docs/topics/rest-hypermedia-hateoas.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/topics/rest-hypermedia-hateoas.md') diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index 0e183a49..b58dfcb7 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -4,15 +4,15 @@ > > — Mike Amundsen, [REST fest 2012 keynote][cite]. -First off, the disclaimer. The name "Django REST framework" was choosen with a view to making sure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs". +First off, the disclaimer. The name "Django REST framework" was choosen simply to sure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs". If you are serious about designing a Hypermedia APIs, you should look to resources outside of this documentation to help inform your design choices. The following fall into the "required reading" category. -* Fielding's dissertation - [Architectural Styles and +* Roy Fielding's dissertation - [Architectural Styles and the Design of Network-based Software Architectures][dissertation]. -* Fielding's "[REST APIs must be hypertext-driven][hypertext-driven]" blog post. +* Roy Fielding's "[REST APIs must be hypertext-driven][hypertext-driven]" blog post. * Leonard Richardson & Sam Ruby's [RESTful Web Services][restful-web-services]. * Mike Amundsen's [Building Hypermedia APIs with HTML5 and Node][building-hypermedia-apis]. * Steve Klabnik's [Designing Hypermedia APIs][designing-hypermedia-apis]. @@ -32,7 +32,7 @@ REST framework also includes [serialization] and [parser]/[renderer] components ### What REST framework *doesn't* provide. -What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] or HTML [microformats] by default, or the ability to auto-magically create HATEOAS style APIs. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. +What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] or HTML [microformats] by default, or the ability to auto-magically create fully HATEOAS style APIs that include form descriptions, and semantically labelled hyperlinks. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. [cite]: http://vimeo.com/channels/restfest/page:2 [dissertation]: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm -- cgit v1.2.3 From 9c1fba3483b7e81da0744464dcf23a5f12711de2 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 15 Oct 2012 13:27:50 +0100 Subject: Tweak parsers to take parser_context --- docs/topics/rest-hypermedia-hateoas.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/topics/rest-hypermedia-hateoas.md') diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index b58dfcb7..dda10eb4 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -24,15 +24,15 @@ For a more thorough background, check out Klabnik's [Hypermedia API reading list REST framework is an agnositic Web API toolkit. It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style. -### What REST framework *does* provide. +## What REST framework *does* provide. It is self evident that REST framework makes it possible to build Hypermedia APIs. The browseable API that it offers is built on HTML - the hypermedia language of the web. REST framework also includes [serialization] and [parser]/[renderer] components that make it easy to build appropriate media types, [hyperlinked relations][fields] for building well-connected systems, and great support for [content negotiation][conneg]. -### What REST framework *doesn't* provide. +## What REST framework *doesn't* provide. -What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] or HTML [microformats] by default, or the ability to auto-magically create fully HATEOAS style APIs that include form descriptions, and semantically labelled hyperlinks. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. +What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] or HTML [microformats] by default, or the ability to auto-magically create fully HATEOAS style APIs that include hypermedia-based form descriptions and semantically labelled hyperlinks. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. [cite]: http://vimeo.com/channels/restfest/page:2 [dissertation]: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm -- cgit v1.2.3 From b5daa40852fb5936e6cddb31ecda5c4b40175cd4 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 17 Oct 2012 13:51:15 +0100 Subject: Docs tweaks --- docs/topics/rest-hypermedia-hateoas.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/topics/rest-hypermedia-hateoas.md') diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index dda10eb4..8b0309b9 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -24,13 +24,13 @@ For a more thorough background, check out Klabnik's [Hypermedia API reading list REST framework is an agnositic Web API toolkit. It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style. -## What REST framework *does* provide. +## What REST framework provides. It is self evident that REST framework makes it possible to build Hypermedia APIs. The browseable API that it offers is built on HTML - the hypermedia language of the web. REST framework also includes [serialization] and [parser]/[renderer] components that make it easy to build appropriate media types, [hyperlinked relations][fields] for building well-connected systems, and great support for [content negotiation][conneg]. -## What REST framework *doesn't* provide. +## What REST framework doesn't provide. What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] or HTML [microformats] by default, or the ability to auto-magically create fully HATEOAS style APIs that include hypermedia-based form descriptions and semantically labelled hyperlinks. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. -- cgit v1.2.3 From 71a93930fd4df7a1f5f92c67633b813a26a5e938 Mon Sep 17 00:00:00 2001 From: Marko Tibold Date: Sun, 21 Oct 2012 16:34:07 +0200 Subject: Fixing spelling errors. --- docs/topics/rest-hypermedia-hateoas.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/topics/rest-hypermedia-hateoas.md') diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index 8b0309b9..d7646892 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -4,7 +4,7 @@ > > — Mike Amundsen, [REST fest 2012 keynote][cite]. -First off, the disclaimer. The name "Django REST framework" was choosen simply to sure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs". +First off, the disclaimer. The name "Django REST framework" was chosen simply to sure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs". If you are serious about designing a Hypermedia APIs, you should look to resources outside of this documentation to help inform your design choices. @@ -22,7 +22,7 @@ For a more thorough background, check out Klabnik's [Hypermedia API reading list ## Building Hypermedia APIs with REST framework -REST framework is an agnositic Web API toolkit. It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style. +REST framework is an agnostic Web API toolkit. It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style. ## What REST framework provides. @@ -50,4 +50,4 @@ What REST framework doesn't do is give you is machine readable hypermedia format [parser]: ../api-guide/parsers.md [renderer]: ../api-guide/renderers.md [fields]: ../api-guide/fields.md -[conneg]: ../api-guide/content-negotiation.md \ No newline at end of file +[conneg]: ../api-guide/content-negotiation.md -- cgit v1.2.3