What is API Developer Experience and Why It Matters


API developer experience is a relatively novel focus aimed to improve API design so it provides a seamless experience to developers when writing software. It can help increase programmers’ efficience and make it easier for developers to achieve goals on behalf of end users.
Jeremiah Lee Cohick, software engineer at Fitbit with a penchant for user experience, frames API experience in the broader developer experience (DX) field. DX encompasses many aspects of the relationship between programmers and the platform they are developing for, such as trust, education, tools, and platform usability. Specifically, he describes API experience as the UX of APIs, which ends up being a critical part of the development cycle phase dedicated to writing code. In a 2014 presentation at Web Directions, Cohick identified four key concerns that can help reach the goal of API excellence:
  • Functionality: what problem the API solves and how good it is at that. An API should not only strive for effectively solving a problem, it should also solve it very well.
  • Reliability: a set of non-functional requirements such as availability, scalability, stability, etc. that can help build trust and represent a necessary ingredient in driving developers to use an API.
  • Usability: how well does an API lend itself to discover and learn how its functionality can be used (intuitability)? How easily does it allow developers to create tests? What support does it provide for error handling?
  • Pleasure: how enjoyable is an API to use?
According to Cohick, when all those pieces fit well together they provide a great developer experience and their absence or imperfection are usually the source of pain and confusion.
Amit Jotwani, Sr. Developer Evangelist & Product Lead at Intel Mashery, says that “people who are really serious about API should care about developer experience”. He suggests ten steps towards great API experience, which :
  • Keep it simple.
  • Avoid marketing jargon and be clear about what developers can stop doing if they use your API.
  • Simple and fast signup, which also includes easy management of API keys, service selection, etc.
  • Fast setup time: ideally, only 5 minutes should be required to create an “Hello World” app.
  • Fast API key provisioning to spare developers long waits.
  • Clarity about costs and limitations; do not create excessive expectations; provide free trial.
  • Provide stellar documentation that is complete and up to date, and avoid using PDFs.
  • Provide interactive documentation, such as the Mashery API explorer and Klout interactive console to make it easier to discover and learn APIs.
  • Show the code, poroviding clear and concise examples of the way an API can be used for a given task.
  • Inspire developers and be available on channels such as Stack Overflow, Twitter, etc.
According to Ronnie Mitra, director of API design at the API Academy, a consulting company helping organizations to improve their APIs, API experience starts from the recognition that developers are people too. The API designer, says Mitra, should set four key goals in order to create an excellent DX:
  • Facilitating troubleshooting (e.g. providing useful error messages)
  • Simplifying change management (e.g. implementing an API versioning strategy)
  • Improving visibility (e.g. providing log and usage access)
  • Establishing trust (e.g. communicating a sense of stability and longevity)
In a talk at the Nordic APIs conference in Stockholm, Mitra proposed a frame similar to Cohick’s to help design great APIs and that has three main pillars: functionality, usability, experience. In this context, usability shifts the focus from the functionality/reliability level towards developers, aiming at making APIs easy to use. Experience concerns itself with how the developer feels about all of the interactions with an API and its providers, and builds on top of both functionality and usability.
According to Mitra, the key to providing a great API experience is to understand its audience. This can be done by defining personas representing typical API consumers.
You can’t design for usability if you don’t know who is using your API
Once personas are defined, usability aspects of an API can be evaluated along several dimensions, based on the work of Steven Clarke at Microsoft:
  • Invocation Ratio: How many calls does it take for the developer to accomplish their desired task?
  • Structure: How deep is the required data located? What is the signal to noise ratio?
  • Navigation: How difficult is it to move from one result to another? How difficult is it to locate a required datum?
  • Developer Stack Size: How many new components are needed?
  • Time to First Call: How quickly can a new user make their first API call?
  • Errors: How difficult are they to fix? What is the nature of the error? (unpredicted result, invalid input, out of sequence, etc…)
Similarly, the experience an API provides have the following aspects: engagement, pleasure, familiarity, trust, and safety, that can be used to guide the design process. Those aspects are a direct product of an API’s usability qualities.

留言

張貼留言

這個網誌中的熱門文章

Json概述以及python對json的相關操作

圖片
什麼是json： JSON(JavaScript Object Notation) 是一種輕量級的數據交換格式。易於人閱讀和編寫。同時也易於機器解析和生成。它基於JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999的一個子集。JSON採用完全獨立於語言的文本格式，但是也使用了類似於C語言家族的習慣（包括C, C++, C#, Java, JavaScript, Perl, Python等）。這些特性使JSON成為理想的數據交換語言。 JSON建構於兩種結構： “名稱/值”對的集合（A collection of name/value pairs）。不同的語言中，它被理解為對象（object），紀錄（record），結構（struct），字典（dictionary），哈希表（hash table），有鍵列表（keyed list），或者關聯數組（associative array）。 值的有序列表（An ordered list of values）。在大部分語言中，它被理解為數組（array）。 這些都是常見的數據結構。事實上大部分現代計算機語言都以某種形式支持它們。這使得一種數據格式在同樣基於這些結構的編程語言之間交換成為可能。 jso官方說 ​​明參見：http://json.org/ Python操作json的標準api庫參考：http://docs.python.org/library/json.html 對簡單數據類型的encoding 和decoding： 使用簡單的json.dumps方法對簡單數據類型進行編碼，例如： import json obj = [[ 1 , 2 , 3 ], 123 , 123.123 , 'abc' ,{ 'key1' :( 1 , 2 , 3 ), 'key2' :( 4 , 5 , 6 )}] encodedjson = json.dumps(obj) print repr (obj) print encodedjson 輸出： [[1, 2, 3], 123, 123.123, 'abc', {'ke...
閱讀完整內容

Docker容器日誌查看與清理

1. 問題 docker容器日誌導致主機磁盤空間滿了。 docker logs -f container_name 劈裡啪啦一大堆，很佔用空間，不用的日誌可以清理掉了。  2. 解決方法 2.1 找出Docker容器日誌 在linux上，容器日誌一般存放在 /var/lib/docker/containers/container_id/ 下面，查看各個日誌文件大小的腳本docker_log_size.sh，內容如下： #!/bin/sh echo "======== docker containers logs file size ========" logs=$(find /var/lib/docker/containers/ -name *-json.log) for log in $logs do ls -lh $log done # chmod +x docker_log_size.sh # ./docker_log_size.sh 2.2 清理Docker容器日誌（治標） 如果docker容器正在運行，那麼使用 rm -rf 方式刪除日誌後，通過 df -h 會發現磁盤空間並沒有釋放。 原因是在Linux或者Unix系統中，通過 rm -rf 或者文件管理器刪除文件，將會從文件系統的目錄結構上解除鏈接（unlink）。 如果文件是被打開的（有一個進程正在使用），那麼進程將仍然可以讀取該文件，磁盤空間也一直被佔用。 正確姿勢是 cat /dev/null > *-json.log ，當然你也可以通過 rm -rf 刪除後重啟docker。 接下來，提供一個日誌清理腳本 clean_docker_log.sh ，內容如下： #!/bin/sh echo "======== start clean docker containers logs ========" logs=$(find /var/lib/docker/containers/ -name *-json.log) for log in $logs d...
閱讀完整內容

利用 Keepalived 提供 VIP

Keepalived 是一種基於 VRRP 協定實現的高可靠 Web 服務方案，用於防止單點故障問題。因此一個 Web 服務運作至少會擁有兩台伺服器執行 Keepalived，一台作為 master，一台作為 backup，並提供一個虛擬 IP（VIP），master 會定期發送特定訊息給 backup 伺服器，當 backup 沒收到 master 訊息時，表示 master 已故障，這時候 backup 會接管 VIP，繼續提供服務，來確保服務的高可靠性。 VRRP VRRP（Virtual Router Redundancy Protocol，虛擬路由器備援協定），是一個提供備援路由器來解決單點故障問題的協定，該協定有兩個重要概念： * VRRP 路由器與虛擬路由器：VRRP 路由器是表示運作 VRRP 的路由器，是一個實體裝置，而虛擬路由器是指由 VRRP 建立的邏輯路由器。一組 VRRP 路由器協同運作，並一起構成一台虛擬路由器，該虛擬路由對外提供一個唯一固定的 IP 與 MAC 位址的邏輯路由器。 * 主控制路由器（master）與備援路由器（backup）：主要是在一組 VRRP 中的兩種互斥角色。一個 VRRP 群組中只能擁有一台是 master，但可以有多個 backup 路由器。 VRRP 協定使用選擇策略從路由器群組挑選一台作為 master 來負責 ARP 與轉送 IP 封包，群組中其他路由器則作為 backup 的角色處理等待狀態。當由於某種原因造成 master 故障時，backup 會在幾秒內成為 master 繼續提供服務，該階段不用改變任何 IP 與 MAC 位址。 Keepalived 節點配置 IP ADDRESS ROLE 172.16.1.101 vip 172.16.1.102 master 172.16.1.103 backup 安裝與設定 這 ubuntu 14.04 LTS Server 中已經內建了 Keepalived 可以透過 apt-get 來安裝： $ sudo apt-get install -y keepalived 也可以透過 source code 進行安裝，流程如下： $ sudo apt-get install build-essential libssl-dev $ wge...
閱讀完整內容