Making Requests

How to Make A Request And Process The Response

Here's a step-by-step example of how to make a request to the Etsy API. This example uses the public endpoint, so no OAuth authentication is required. For an example using OAuth, see the next section.

We'll make a request to get details for the user that runs the official Etsy store, "EtsyStore" using the getUser method. You can also substitute your own user name for "EtsyStore". If you consult the documentation for that method, you'll see the following:

Every Etsy API request begins with the base URL:

https://openapi.etsy.com/v2

and ends with the URI for the command.  The part of the URI that reads :user_id is an embedded parameter—you'll need to substitute either the user name "etsystore" or the ID of the user you're trying to access.

Finally, you'll add a question mark (?) plus any optional parameters you'd like to send, and of course, your API key.  The final request looks like this:

https://openapi.etsy.com/v2/users/etsystore?api_key=your_api_key

You can test this right in your browser.  You should see a long string of JSON data language.  Note that the object returned is of resource type User.  See User in the API Reference for more details.

Sample Request from PHP

Here is an example of a call in a PHP script. You can use any language that supports HTTP requests (JavaScript, Ruby, Perl...) which is just about every language in use on the web.

// Make sure you define API_KEY to be your unique, registered key
$url = "https://openapi.etsy.com/v2/users/etsystore?api_key=" . API_KEY;
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response_body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (intval($status) != 200) throw new Exception("HTTP $status\n$response_body");

Notice that in line #6 we're using the value of $response_body as an error message.  In the event of an error, the response body will contain a plaintext formatted explanation of the problem. The error will not be JSON encoded.

Sample Response

Here's the response from our request above (with added white space to make it easier to read.)  The response is formatted using JSON, a simple data serialization language that can be used by just about any language on the web.  (Find JSON support for your language.)

{
  "count": 1,
  "results": [
    {
      "user_id": 5029420,
      "login_name": "EtsyStore",
      "creation_tsz": 1166740121,
      "referred_by_user_id": null,
      "feedback_info": {
        "count": 2559,
        "score": 100
      }
    }
  ],
  "params": {
    "user_id": "etsystore",
  },
  "type": "User"
}

Notice that in the response above, the user name "etsystore" that you passed in has been helpfully converted into a user ID.  Since it's slightly more efficient to look up users by ID, we suggest that you use the ID for subsequent requests.

Sample Response in PHP

And here's how we'd parse and use the response in PHP:

$response = json_decode($response_body);
$user = $response->results[0];

if (!isset($user->login_name)) {
    throw new RuntimeException("User Resource doesn't have field login_name");
}
if (!isset($user->feedback_info->score)) {
    throw new RuntimeException("User Resource doesn't have field feedback_info['score']");
}
print "User $user->login_name has a feedback score of {$user->feedback_info->score}\n";