From 7aee4a8ab5c4ac6203dc31e3082bde3f36173445 Mon Sep 17 00:00:00 2001 From: Mark Date: Wed, 5 Aug 2015 11:38:28 +1000 Subject: [PATCH 01/10] Fairly significant editorial changes. Suggested changes don't change the substance of the message, but are aimed to simplify and improve flow. --- preface.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/preface.rst b/preface.rst index a895411..a498eb0 100644 --- a/preface.rst +++ b/preface.rst @@ -1,27 +1,29 @@ Preface to the API Design Guide =============================== -Like websites and hand-held device apps, APIs (Application Programming Interfaces) are just another channel for delivering services online. APIs already power many of today's websites and apps, and in the future they are likely to become more important. This is not because they are the cheapest, fastest, most cost effective way to deliver some kinds of digital services. It's because they can be incorporated into downstream applications that recombine them in creative ways. Good APIs are a case of less being more, stripping a digital service down to it's simplest possible form, so that the value of the service can be amplified through reuse. +Like websites, shop-fronts and call centres, APIs (Application Programming Interfaces) could be viewed as simply another channel for delivering services online. APIs power many of today's websites and mobile apps, and are becoming increasingly important in the digital economy. This is because APIs can be incorporated into downstream applications, whereby third-parties reuse and recombine them in creative ways. Good APIs strip a digital service down to it's simplest possible form, so that the value of the service can be amplified through third-party reuse. -The principle of user-centred design is at the core of website and application development. It's about ergonomics; can a user "consume a digital service" without bad design getting in their way? Getting this right requires empathy for users, validated by real user experiences. It's at least a well known principle, if not always well practised. +The principle of user-centred design is at the core of website and application development. It's about ergonomics; can a user "consume a digital service" without bad design getting in their way? Getting this right requires empathy for users, backed by evidence regarding user-preferences. Although a well known principle, it is not always well practised. -In some ways, developer empathy is exactly the same; developers are people too. But when developers create value by exploiting an API, they can deliver it to many people. A successful user interaction is a single service delivery event, a single good user experience. A successful API integration is a long lever that can result in many good user experiences. +In some ways, developer empathy is exactly the same; developers are people too, and the 'users' of web APIs. The key difference is that when developers 'use' an API, they often create additional value for many people. A well designed end-user experience results in a single good user experience. A well-designed API on the other hand can result in many good user experiences, often enjoyed by those the original service designer did not envision. .. epigraph:: We have developer empathy. If our interfaces are hard to use, we consider that a bug. We are an engineer-led company. Everything we do tries to be compatible with our API. - -- Steve Mayzac, ElasticSearch (around 6.20 into https://www.youtube.com/watch?v=uxfvNwl_MGc). + -- Steve Mayzac, Amazon ElasticSearch (around 6.20 into https://www.youtube.com/watch?v=uxfvNwl_MGc). -User empathy is focused on ergonomics at the point of delivery. Developer empathy is focused on the software integration experience. It's still fundamentally about ergonomics but the context is different. As a user, successful design has the quality of affordance (obviousness, "don't make me think"). As a developer, successful design also means knowing how to use an API (affordance through idioms, adequate documentation) and functional fit for a previously unimagined application, but also knowing how and when things are going to change and other stuff that matters in a business partnership with someone else's IT system. +User empathy is focused on ergonomics at the point of delivery. Developer empathy is focused on painless systems integration. Good API design is still fundamentally about ergonomics, but the context is different. As a user, successful design has the quality of affordance (obviousness, "don't make me think"). For developers, good API design also incorporates this quality (through idioms and good documentation). Further, good API design allows developers to integrate their applications with your systems in a decoupled manner; they are able to reuse the resources exposed by your API in previously unimagined ways. Lastly, good APIs are stable and adhere the 'principle of least surprise': developers are able to rely on your API to behave in a predictable manner. -The gold standard in developer empathy is found in thriving open source projects. Collaboration, peer review and a responsiveand supportive community. Organisations that do well in this space nurture their relationship with developers as though their survival depends on it. This does not describe Australian Government IT of today, but it just might describe the "government as a platform" of the future. Some things are certain; APIs are important, their importance is growing, developer empathy is important and we need all the help we can get. +The gold standard in developer empathy is found in thriving open source projects. Collaboration, peer review and a responsivecommunity are the hallmarks of such projects. Organisations that do well in this space nurture their relationship with developers as though their survival depends on it (quite often because it does). This does not describe Australian Government IT of today, but hopefully describes the "government as a platform" of tomorrow. Some things are certain: APIs are important, they can generate additional and significant value, developer empathy is critical to successs and we need all the help we can get. -The DTO was about to release a draft API design guide which describes developer empathy as a key principle behind contemporary best practices. When launched, this document will be mandatory policy that all Commonwealth agencies will be obliged to follow, and citizens will be entitled to expect. The purpose of releasing a draft is to get feedback, but at the last minute we had a better idea... +The DTO planned to release a draft API design guide describing contemporary best practices in API design and developer empathy. The final document would be mandatory policy that all Commonwealth agencies must follow, and that citizens could be entitled to expect. The purpose of releasing a draft was to get feedback, but at the last minute we had a better idea... -We want feedback from developers, right? What if we converted it to a developer-friendly format, published in a version control system, opened a public ticket system for issues and support, and invited pragmatic people everywhere to help us make it better? Done: +We want feedback from developers, right? So we figured: why not converted it to a developer-friendly format, published in a version control system with a public ticket system for issues and support, and invited our users to help us make it better? + +Done. * read https://apiguide.readthedocs.org/ * discus https://github.com/AusDTO/apiguide/issues From 3b018cdf2fb97e1fa8f035e148af77c892704e32 Mon Sep 17 00:00:00 2001 From: Chris Gough Date: Wed, 5 Aug 2015 12:06:28 +1000 Subject: [PATCH 02/10] fix typo, remove quotes around 'user' and 'use' I think it looks better without those quoted :) --- preface.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/preface.rst b/preface.rst index a498eb0..f69c52c 100644 --- a/preface.rst +++ b/preface.rst @@ -5,7 +5,7 @@ Like websites, shop-fronts and call centres, APIs (Application Programming Inter The principle of user-centred design is at the core of website and application development. It's about ergonomics; can a user "consume a digital service" without bad design getting in their way? Getting this right requires empathy for users, backed by evidence regarding user-preferences. Although a well known principle, it is not always well practised. -In some ways, developer empathy is exactly the same; developers are people too, and the 'users' of web APIs. The key difference is that when developers 'use' an API, they often create additional value for many people. A well designed end-user experience results in a single good user experience. A well-designed API on the other hand can result in many good user experiences, often enjoyed by those the original service designer did not envision. +In some ways, developer empathy is exactly the same; developers are people too, and the users of web APIs. The key difference is that when developers use an API, they often create additional value for many people. A well designed end-user experience results in a single good user experience. A well-designed API on the other hand can result in many good user experiences, often enjoyed by those the original service designer did not envision. .. epigraph:: @@ -17,7 +17,7 @@ In some ways, developer empathy is exactly the same; developers are people too, User empathy is focused on ergonomics at the point of delivery. Developer empathy is focused on painless systems integration. Good API design is still fundamentally about ergonomics, but the context is different. As a user, successful design has the quality of affordance (obviousness, "don't make me think"). For developers, good API design also incorporates this quality (through idioms and good documentation). Further, good API design allows developers to integrate their applications with your systems in a decoupled manner; they are able to reuse the resources exposed by your API in previously unimagined ways. Lastly, good APIs are stable and adhere the 'principle of least surprise': developers are able to rely on your API to behave in a predictable manner. -The gold standard in developer empathy is found in thriving open source projects. Collaboration, peer review and a responsivecommunity are the hallmarks of such projects. Organisations that do well in this space nurture their relationship with developers as though their survival depends on it (quite often because it does). This does not describe Australian Government IT of today, but hopefully describes the "government as a platform" of tomorrow. Some things are certain: APIs are important, they can generate additional and significant value, developer empathy is critical to successs and we need all the help we can get. +The gold standard in developer empathy is found in thriving open source projects. Collaboration, peer review and a responsive community are the hallmarks of such projects. Organisations that do well in this space nurture their relationship with developers as though their survival depends on it (quite often because it does). This does not describe Australian Government IT of today, but hopefully describes the "government as a platform" of tomorrow. Some things are certain: APIs are important, they can generate additional and significant value, developer empathy is critical to successs and we need all the help we can get. The DTO planned to release a draft API design guide describing contemporary best practices in API design and developer empathy. The final document would be mandatory policy that all Commonwealth agencies must follow, and that citizens could be entitled to expect. The purpose of releasing a draft was to get feedback, but at the last minute we had a better idea... From bb41a952f8a7e8d950a135eea3f07fb6e959d5e5 Mon Sep 17 00:00:00 2001 From: Mark Date: Wed, 5 Aug 2015 16:01:06 +1000 Subject: [PATCH 03/10] Narrowed conformance criteria, emphasised simplicity and economic rationale Have narrowed the conformance criteria slightly. We should probably sit down and work out our full set of criteria, with an eye to keeping it short and simple. This will also make it less burdensome for developers to provide feedback, and easier for agencies to run through the full conformance suite. Have also placed a stronger emphasis on 'simplicity', and given the public policy rationale as to why we want to make it easy for developers to use our APIs. --- principles/empathy.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/principles/empathy.rst b/principles/empathy.rst index b398395..1e2503b 100644 --- a/principles/empathy.rst +++ b/principles/empathy.rst @@ -3,8 +3,12 @@ Developer empathy **Design with developer empathy** -Developers are users too and the same principles of user-centred-design apply to the development and publishing of APIs – except that your user is a developer that wants to consume your API rather than an end user that is a customer for the government service or data. Most of the other criteria in this guide are traceable to this criteria. +When it comes to APIs, developers are your users. The same principles of user-centred-design apply to the development and publication of APIs (simplicity, obviousness, fit-for-purpose etc). Most of the other criteria in this guide are traceable to the principles of good design. Perhaps the most important criteria to be mindful of is *simplicity*: as with any other product, people simply won't use something if it is hard to use. -All Government APIs will be published to a central service register as described in Building and publishing APIs. The service register will provide a mechanism for developers to provide feedback on APIs. An API that is consistently rated as hard to use should be considered defective. +Hard-to-use APIs create bad public policy outcomes: +- Potentially significant economic value will remain undiscovered or unrealised +- Secondary markets that form around APIs (e.g. automated tax reporting software) will be less competitive, and therefore less efficient (API complexity creates barriers to market entry) -**Conformance Criteria:** less than 20% of feedback rates the API as poor. +To ensure dicoverability and accountability, all Government APIs will be published to a central service register (as described in Building and Publishing APIs secion [insert link]). The service register will give developers a mechanism to provide feedback on APIs. An API that is consistently rated as hard to use will be deemed defective and should be remediated. + +**Conformance Criteria:** less than 20% of feedback rates the API as hard to use. From 6cfcb87bd30b7fc8ee7d40a6bab808849a213e11 Mon Sep 17 00:00:00 2001 From: lhowdin Date: Fri, 7 Aug 2015 10:05:38 +1000 Subject: [PATCH 04/10] Tagline --- preface.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/preface.rst b/preface.rst index f69c52c..778a034 100644 --- a/preface.rst +++ b/preface.rst @@ -1,6 +1,8 @@ Preface to the API Design Guide =============================== +A design guide with developer empathy. + Like websites, shop-fronts and call centres, APIs (Application Programming Interfaces) could be viewed as simply another channel for delivering services online. APIs power many of today's websites and mobile apps, and are becoming increasingly important in the digital economy. This is because APIs can be incorporated into downstream applications, whereby third-parties reuse and recombine them in creative ways. Good APIs strip a digital service down to it's simplest possible form, so that the value of the service can be amplified through third-party reuse. The principle of user-centred design is at the core of website and application development. It's about ergonomics; can a user "consume a digital service" without bad design getting in their way? Getting this right requires empathy for users, backed by evidence regarding user-preferences. Although a well known principle, it is not always well practised. From 184efe2301c8af5d425270613369e84af806ab43 Mon Sep 17 00:00:00 2001 From: Chris Gough Date: Fri, 7 Aug 2015 10:51:22 +1000 Subject: [PATCH 05/10] embolden the tagline --- preface.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/preface.rst b/preface.rst index 778a034..82f98d9 100644 --- a/preface.rst +++ b/preface.rst @@ -1,7 +1,7 @@ Preface to the API Design Guide =============================== -A design guide with developer empathy. +**A design guide with developer empathy**. Like websites, shop-fronts and call centres, APIs (Application Programming Interfaces) could be viewed as simply another channel for delivering services online. APIs power many of today's websites and mobile apps, and are becoming increasingly important in the digital economy. This is because APIs can be incorporated into downstream applications, whereby third-parties reuse and recombine them in creative ways. Good APIs strip a digital service down to it's simplest possible form, so that the value of the service can be amplified through third-party reuse. From 55caf117e389400e1bad20e3ef31181b3faefd27 Mon Sep 17 00:00:00 2001 From: Sean Minney Date: Tue, 11 Aug 2015 16:48:27 +1000 Subject: [PATCH 06/10] Update preface.rst --- preface.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/preface.rst b/preface.rst index 82f98d9..19324bd 100644 --- a/preface.rst +++ b/preface.rst @@ -23,7 +23,7 @@ The gold standard in developer empathy is found in thriving open source projects The DTO planned to release a draft API design guide describing contemporary best practices in API design and developer empathy. The final document would be mandatory policy that all Commonwealth agencies must follow, and that citizens could be entitled to expect. The purpose of releasing a draft was to get feedback, but at the last minute we had a better idea... -We want feedback from developers, right? So we figured: why not converted it to a developer-friendly format, published in a version control system with a public ticket system for issues and support, and invited our users to help us make it better? +We want feedback from developers, right? So we figured: why not convert it to a developer-friendly format, published in a version control system with a public ticket system for issues and support, and invited our users to help us make it better? Done. From d94c4a37022f22ee2fedf94665f6a40647f0e027 Mon Sep 17 00:00:00 2001 From: Chris Gough Date: Thu, 13 Aug 2015 12:04:10 +1000 Subject: [PATCH 07/10] massive caveat on mandate to create APIs I realised I had contradicted this page in comments on my blog, and after discussion with the original author learned that this was a deliberate provocation designed to provoke discussion. Since that hasn't happened, I'm calling it out. --- build_and_publish/index.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/build_and_publish/index.rst b/build_and_publish/index.rst index 1fd1363..63e7968 100644 --- a/build_and_publish/index.rst +++ b/build_and_publish/index.rst @@ -8,6 +8,13 @@ Agencies must provide API access to their data and services when any of the foll * Any authoritative public data sources containing over 50,000 records. * Any new or refreshed digital service. +.. note:: + + The above statement is a deliberate provocation, designed to encourage discussion around when APIs should + and should not be developed. A mandate like that would require appropriate consultation. If you have comments + or suggestions about this, please raise a ticket (or pull request). + + Agencies are encouraged to make all digital services available as an API, even when below the thresholds specified. It is recommended that agencies deliver all APIs following ‘Pragmatic REST’ (Representational state transfer) principles detailed below. From 1b8c14be3cbf4320994b4fd14ec1cb225ee4bd14 Mon Sep 17 00:00:00 2001 From: Nigel O'Keefe Date: Thu, 20 Aug 2015 10:04:24 +1000 Subject: [PATCH 08/10] Correct value in keys example As proposed in issue #41 by @clockwisemusic This fixes #41 --- build_and_publish/use_HTTP_methods.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build_and_publish/use_HTTP_methods.rst b/build_and_publish/use_HTTP_methods.rst index f17c667..5c6a4d7 100644 --- a/build_and_publish/use_HTTP_methods.rst +++ b/build_and_publish/use_HTTP_methods.rst @@ -243,7 +243,7 @@ Examples HTTP response principles ------------------------ -No values in keys – for example, {"125": "Environment"} is bad, {"id": "125", "name": "Environment"} is good. +No values in keys – for example, {“125”, “Environment”} is bad, {“id”: “125”, “name”: “Environment”} is good. No internal-specific names (for example, "node" and "taxonomy term") From ed40d49aa603334b16c39eae6e10793e936dc805 Mon Sep 17 00:00:00 2001 From: Chris Gough Date: Sat, 22 Aug 2015 00:13:06 +1000 Subject: [PATCH 09/10] revert changes to example syntax syntax error created when responding to feedback about unclear syntax (this change fixes 41). --- build_and_publish/use_HTTP_methods.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build_and_publish/use_HTTP_methods.rst b/build_and_publish/use_HTTP_methods.rst index 5c6a4d7..51109c7 100644 --- a/build_and_publish/use_HTTP_methods.rst +++ b/build_and_publish/use_HTTP_methods.rst @@ -243,7 +243,7 @@ Examples HTTP response principles ------------------------ -No values in keys – for example, {“125”, “Environment”} is bad, {“id”: “125”, “name”: “Environment”} is good. +No values in keys – for example, {“125”: “Environment”} is bad, {“id”: “125”, “name”: “Environment”} is good. Note that in the first (bad) example, the key is "125" and the value is "Environment". This is a problem because the key is supposed to be the name of the value. In the second example (good) the keys are descriptions of their coresponding values. No internal-specific names (for example, "node" and "taxonomy term") From 2f4744c1ddbf4dc994d7b38fe70dfee1ceb0241c Mon Sep 17 00:00:00 2001 From: Chris Beer Date: Mon, 24 Aug 2015 09:23:08 +1000 Subject: [PATCH 10/10] Update hateos.rst Corrected typo in heading --- build_and_publish/hateos.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build_and_publish/hateos.rst b/build_and_publish/hateos.rst index d004e7d..adc627b 100644 --- a/build_and_publish/hateos.rst +++ b/build_and_publish/hateos.rst @@ -1,4 +1,4 @@ -Manageme state with HATEOAS +Management state with HATEOAS =========================== “Hypermedia As The Engine Of Application State” (HATEOAS) is a RESTful technique that can make consumer applications simpler and more robust. In many applications, the allowed actions on a resource depend on the state of that resource. Rather than require the consumer to understand and code for the allowed states, HATEOAS provides a means for the server to say what is allowed. The concept is best explained by example.