Percent encoding parameters

This page covers the URL encoding process described in RFC 3986, Section 2.1. Reference that specification in case of any ambiguity or conflict with this document.

Overview

Parts of the Twitter API, particularly those dealing with OAuth signatures, require strings to be encoded according to RFC 3986, Section 2.1. Since many implementations of URL encoding algorithms are not fully compatible with RFC 3986, bad encodings are a cause of many OAuth signature errors. For this reason, the exact signing algorithm to use is covered on this page.

Encoding a string

The following algorithm assumes you are encoding a string SRC by copying its values byte-by-byte to a string DST.

Step 1: While SRC contains unread bytes, read the next byte (8 bits) from SRC. Typically, this is considered a character, but in the case of encodings where a character may be more than one byte (such as UTF-8), just read the first byte.

Step 2: Check whether the read byte matches any of the following ASCII equivalents. The following table has been broken down into rows for legibility, but you only need to determine whether the read byte exists in the table at all, not the specific row.

Step 2b: If the byte is not listed in the above table, continue. Any other value must be encoded.Step 2a: If the byte is listed in the above table, copy it into DST and go back to Step 1. Characters listed in the above table do not need to be escaped, so you will just copy the byte directly.

Step 3: Write the character ‘%’ to DST. The percent character ‘%’ (or 0x25 in hex and 00100101 in binary) indicates that the next two bytes will represent an encoded byte.

Step 4: Write two characters representing the uppercase ASCII-encoded hex value of the current byte to DST.This is a bit confusing, so here is an example. Pretend the current byte is 0xE6 (11100110 in binary). This corresponds with the UTF-8 encoded value of ‘æ’. To encode this value, write the character ‘E’ (0x45, from the table above) and then the character ‘6’ (0x36) to DST. The last three characters written should have been “%E6”. Note that if you write a letter such as A,B,C,D,E or F, you must use the uppercase character.

Step 5: Return to Step 1. Keep going until the entirety of SRC is copied to DST.

Examples

The following examples may be helpful to compare with the output of your own code. You should consider any differences an error. Spaces encoded as “+” characters are an example of incorrect encoding.