Sharetribe's Postman collection

Postman Collections are a way to group HTTP requests. Using Postman, you can fork and clone existing Collections and use them to test and develop against different APIs. We recently introduced a Postman Collection that documents our APIs and allows you to test and explore our endpoints. The Collection can be practical when developing a custom client application or building new features that you're building using our APIs. In this blog post, we'll introduce how to use the Collection and show some examples of how you can use it to help develop your marketplace.

The Sharetribe API consists of the following individual APIs:

• Marketplace API
• Integration API
• Authentication API
• Asset Delivery API

Setup Postman

To begin using the Postman Collection, you'll need Sharetribe and Postman accounts. 

After you've created both, you'll need to fork the Collection. The fork is a copy of the Collection, which you can modify and use to test the API against your marketplace data.

The Collection uses pre-request scripts, which run before each API call. The pre-request scripts handle authentication based on the Collection variables, which store the API keys allowing access to your marketplace's data. The pre-request scripts differ based on the calls you're making; different endpoints require different levels of authorization.

To use the Collection, you must add your Sharetribe Client IDs and Secrets to the Collection variables. You can discover the variables in the Sharetribe Console:

1. Open the Sharetribe Console and navigate to the left-hand panel.
2. Choose the "Dev" environment from the environment picker and enable it.
3. Go to Advanced => Applications and create a new Marketplace API application.
   undefined
4. To use the Integration API, also create an Integration API application.
   undefined
5. Some requests require user authentication. To enable these requests, create a user in your marketplace application and store the username and password in the collection variables.

Remember not to use your Live keys when testing! Only use the keys from either your Test or Dev environments.

Once you've saved the Client IDs and Secrets to the Collection variables, you can start making API calls via Postman!

Authorization

The Sharetribe API provides an Authentication API, which you can use to retrieve an access token. Every call to the Marketplace and Integration API requires a valid access token. You must pass the access token in the Authorization HTTP header of each API request. There are four different types of access tokens:

1. Anonymous access token
2. User access token
3. Trusted user access token
4. Integration access token

Anonymous access token

The anonymous access token allows you to access Marketplace API resources that provide data intended for a public audience. Examples of public data include the listings endpoint and the show-user endpoint. Listing and user data are relevant even for users not logged in, and these endpoints do not reveal any sensitive data. To receive the anonymous access token, you only need to provide the Client ID of your marketplace application. The Client ID is publicly discoverable via the source code of your marketplace application if you're using the Sharetribe Web Template.

User access token

The user access token provides access to endpoints that manipulate user data or fetch private user data. Examples are all current-user endpoints (with the create-user endpoint being an exception), such as the update-user or change-password endpoints. The user access token requires you to pass the Client ID, the username, and password alongside the request to the Authentication API.

Trusted user access token

Sometimes, endpoints require a Trusted user access token. For example, some transitions within a transaction process can include privileged actions that you need to call from a trusted context. Actions like this include setting the transaction line items and updating the transaction metadata. Notably, the transition-transaction endpoint does not always expect a trusted user access token; it is only necessary when the transition contains a privileged action. The trusted user access token is obtained by passing the Authentication API the Application client secret and a valid user access token, obtained using the user's credentials and not a refresh token.

Integration access token

The Integration API provides full access to your marketplace data. It can be practical for building integrations and complex custom functionality when the marketplace API isn't sufficient. To access the Integration API, you need an Integration access token. The token is obtained by passing the Client ID and Client Secret of your marketplace application in the Authentication API request. It is very important to never reveal the Client Secret publicly; access to it grants full access to all marketplace data, which can cause a lot of damage in the wrong hands.

Pre-request scripts

The Sharetribe Postman collection uses pre-request scripts to handle authorization. Pre-request scripts are assigned by folder and triggered before each request. The only exceptions are all the Authentication API requests. The pre-request scripts use the environment variables associated with your fork of the Sharetribe API collection to retrieve the correct user access token. The script stores the access token, the refresh token, and the access token's expiration time in the environment variables. If a valid access token already exists, the pre-request script is not run. If an expired token exists, the script uses the refresh token to fetch a valid access token.

You can also use the Authentication APIs to directly retrieve access tokens. This may be necessary if one of your requests requires a trusted user access token, as the pre-request script associated with the transition-transaction endpoint only fetches a regular user access token.

To override the access token used by the pre-request script, you can copy and paste the bearer token you receive from the Authentication API and override the variable stored in the Authorization field of the request.

Collection variables

You can find the Collection variables under the Variables tab. There are six assigned by default:

• client_id
• client_secret
• base_url
• username
• password
• integration_id
• integration_secret

These are used for the pre-request scripts which automatically authorize the request you make to any of the APIs.

You can leave these empty if you want to Authenticate by using the Authentication API directly. You'll also need to disable the pre-request scripts if you're leaving the Collection variables empty, as the pre-requests scripts will fail if no Collection variables are present, blocking the actual request from succeeding. 

client_id & client_secret

You can find these values in your Sharetribe Console, under Advanced > Applications. You'll need to create a Marketplace Application and copy the Client ID and Client Secret values.

base_url

This value is by default https://flex-api.sharetribe.com. You don't need to change this value if you're not using a proxy to route your API calls.

username

Use the username of either an existing user in your marketplace (their email) or create a new user. The pre-request script uses this to fetch a user access token.

password

Use the password that matches the user account associated with the username. The pre-request script uses this to fetch a user access token.

integration_id & integration_secret

You can find these values in your Sharetribe Console, under Advanced > Applications. You'll need to create a Integration API Application and copy the Client ID and Client Secret values.

In addition to these Collectin variables, the pre-request scripts will store additional values to the variables, such as access tokens, refresh tokens, and their expiration times.

POST and GET HTTP requests

All HTTP requests in the Collection are either POST or GET requests. The difference between these two request methods is determined by the nature of the operation being performed. A POST request is used to submit data to be processed to a specified resource, creating a new resource or updating existing ones. A GET request is used to retrieve data from a specified resource, and it should not have the effect of modifying the resource.

The main difference in usage is how you pass data with the request. In all GET requests, you use query parameters, which are defined in the following view:

In a POST request, you need to edit the JSON formatted data in the Body tab of the request:

All the requests in the Collection include examples of the correct data format. Check out the API documentation for more detailed instructions on how to use each endpoint.

Including related resources

Most resource types have relationships to other resources. When a given resource type has related resources, clients may request that the related resources be included in API responses for that given resource type. For example, when querying listings, you may want to include all images and image URLs.

You can include related resources by adding an "include" query parameter to the API request. The value is a comma-separated list of relationships to include. 

For example, if you want to include all images when querying listings, you would use the following request:

https://flex-api.sharetribe.com/v1/api/listings/query?include=images 

When a relationship is included, the main resource contains a relationship object, and the overall response JSON object has a top-level key "included":

{
    "data": [
        {
            "id": "a1b2c3d4-e5f6-4a5b-9c8d-1e2f3a4b5c6d",
            "type": "listing",
            "attributes": {
                "title": "New Bicycle",
                "state": "published",
                "publicData": {
                    "brand": "diamant",
                    "category": "city-bikes",
                    "location": {
                        "address": "123 Main Street, Anytown, AT 56789, Anyland"
                    },
                    "price": {
                        "amount": 20000,
                        "currency": "GBP"
                    }
                }
            },
            "relationships": {
                "images": {
                    "data": [
                        {
                            "id": "b1c2d3e4-f5g6-4a5b-9c8d-1e2f3a4b5c6d",
                            "type": "image"
                        }
                    ]
                }
            }
        }
    ],
    "included": [
        {
            "id": "b1c2d3e4-f5g6-4a5b-9c8d-1e2f3a4b5c6d",
            "type": "image",
            "attributes": {
                "variants": {
                    "default": {
                        "url": "https://sharetribe.imgix.net/..."
                    }
                }
            }
        }
    ]
}

Security

Do not share your API keys or any personal data unintentionally with anyone. The Integration API grants full access to your whole marketplace data, meaning you should take particular care not to expose them to anyone unauthorized. Do not use your Live marketplace credentials to test API calls with this Collection. Only use the credentials from your Test and Dev environments for testing purposes.

Do not persist collection variables that contain sensitive data when sharing your forked Postman collection.