I like to learn about how people design apis. There are a bunch of decisions that can make working with an api delightful or painful. A probably not exhaustive list:

  • Security
    • Authentication
    • Authorization
    • Logging
    • Quotas, limits, fairness
  • Documentation
  • Consistency
  • Language (resources, actions)
  • Messaging patterns
  • Response formats
  • Callbacks, webhooks
  • Sandboxes vs production
  • Helper libraries to get you started

Looking at twilio’s api today!

Starts with a great definition of what an api is:

An API is an application programming interface - in short, it’s a set of rules that lets programs talk to each other, exposing data and functionality across the internet in a consistent format.

  • Http basic for authention with tls. Nice and simple!
  • Helper client libraries (language specific) for interacting with the api to help developers get started in the language of their choice more quickly (Java, Javascript, C#, …)
    • Language library dependencies can be added using standard community packaging systems (eg maven, npm)
  • https://api.twilio.com/2010-04-01///action
  • Guide sections not specifically about the api itself
    • Developer getting started doc talks about local environments by supported language with a simple started script
    • Debugging
    • Good practice for interacting with rest apis
  • Responses
    • Formats: json, xml
    • Requested on url by passing an extension (eg .json)
  • Resource lists: paging for long lists, page number, next page uri, prev page uri, first page
  • Errors: embedded doc in a standard response envelope => { …, RestException: { … } }
  • Data,time formatting RFC 2822 (eg “Fri, 20 Aug 2010 01:13:42 +0000”)
    • RFC 8601 is another popular standard

Sample java send sms message

// Install the Java helper library from twilio.com/docs/libraries/java
import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Message;
import com.twilio.type.PhoneNumber;

public class SmsSender {
    // Find your Account Sid and Auth Token at twilio.com/console
    public static final String ACCOUNT_SID =
    public static final String AUTH_TOKEN =

    public static void main(String[] args) {
        Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

        Message message = Message
                .creator(new PhoneNumber("+14159352345"), // to
                        new PhoneNumber("+14158141829"), // from
                        "Where's Wallace?")


Sample error

  "status": 400,
  "message": "No to number is specified",
  "code": 21201,
  "more_info": "http:\/\/www.twilio.com\/docs\/errors\/21201"

twilio api docs

  • Easy navigation, main content, and sample messages+code


  • https://www.twilio.com/docs/usage/api
  • https://www.twilio.com/docs/libraries
  • https://www.twilio.com/docs/usage/rest-api-best-practices