Merge branch 'master' of github.com:AusDTO/hackme

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.  

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.

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")
 

preface.rst

@@ -1,27 +1,31 @@
 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.
+**A design guide with developer empathy**.
 
-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.
+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.
 
-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.
+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.
 
 .. 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 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.
 
-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.
+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 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 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...
 
-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...
+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? 
 
-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:
+Done.
 
  * read https://apiguide.readthedocs.org/
  * discus https://github.com/AusDTO/apiguide/issues

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.