Answers for questions about APIs in issue 24 and 25 - rosalsm/TIY-GitHub GitHub Wiki

How do I make API requests?

GET - Reads a resource. Returns HTTP 200 on success.

What is the base URL for all requests?

https://openapi.etsy.com/v2/listings/:listing_id

:listing_id is the unique id of resources and we have to change it for the correct placeholder before making a call

Are there any headers or query parameters required?

Yes, we need query parameters of the URL itself or as POST parameters. Those parameters are: string, int, epoch, float, boolean, user_id_or_name, shop_id_or_name, team_id_or_name,etc.

What kind of response should I expect?

The response format will be wrapped in a standard structure like:

{
     "count":integer,
     "results": [
         { result object }
     ],
     "params": { parameters },
     "type":result type
}

Where count specified the total number of results available for this call. results will be and array fo results. params will be the parameters that were passed in the request. type specified the type of objects in the results array.

How does the API handle authentication?

Etsy API requires an application key that is provided during app registration. This key identifies your application to the Etsy web service and used to track overall call usage. You need this application key to start the OAuth authentication process.

Do I need to authenticate? with user credentials?

Only with connectUsers and unconnectUsers?

What can I do with an unauthenticated request?

Find users by name, id and team; circled a specific user, get details about a connection between users

How can I authenticate my request? (what methods)

By using OAuth 1.0 to allow both read and write access to user's private data.

Method: permission scopes allows apps to be more specific about the operations they intend to perform against an Etsy member's account and what data can be read with a given set of OAuth credentials.

obtain temporary credentials. an app requests a set of temporary credentials ("request token".) you'll send requests with your consumer key (api key) signed with your shared secret. if match, will return temp credentials (including OAuth token and token secret) pass one or more permission scopes depending on what aspects of the member's account you'd like to access. ex: listing_w (create and edit a member's listings) the app directs the member to a page on Etsy where the temp credentials are approved and linked to the member's account. Click on the "allow access" button. will return verifier token. then return to your app and enter in the verifier token. the app exchanges the temp creds for permanent token credentials ("access token".) These credentials give the app limited access to the member's account using the API. setToken() will set the final tokens and make the call to the Etsy API.

Issue 25

What Resource in the API represents...

an individual product?

Items for sale on Etsy are called listings. Each Etsy listing has a number of associated resources, which taken as a whole, describe the entire item for sale. Listing is the main resource and contains the item description and quantity currently available.

a group or collection of products?

Each listing is indirectly associated with one Shop (note that the true association is made between users and listings.) Use findAllShopListingsActive to query the currently available listings for a shop. Each shop can optionally have one or more ShopSections Use findAllShopSections to find all the sections for a given shop.

images associated with a product?

Each listing can have up to five images, uploaded by the seller. Use either the MainImage or Images associations of Listing to retrieve these images. You can also use the dedicated findAllListingImages method.

sizes and colors for a product?

What actions and endpoints exist for each of these Resources? What parameters do each endpoint require or accept? What fields are returned for each Resource, specifically: an individual product? listing a group or collection of products? shop What additional fields can be requested for each?