Trying it in Postman

To try the API before you write any code, use the Postman collection that comes with this guide. It has a request for every operation, in the order you’d try them, with the sign-in set up once for the whole collection. Each request saves what the next one needs (a share id, a path, an ETag), so you can work down the folders by clicking Send.

Two files come with this guide:

File	What it is
foldr-api-v1.postman_collection.json	The collection: the requests, the OAuth settings and the scripts that carry values from one request to the next.
foldr-site.postman_environment.json	An environment: your site’s address, the app’s client ID, and the values the requests fill in as you go.

Postman’s desktop app runs the requests itself, not from a web page, so the API’s lack of CORS headers doesn’t get in the way. The web version of Postman needs the Postman Agent for the same reason.

Before you start

You need a Foldr site with connected apps switched on, and a person on it who may connect apps. Both are an administrator’s settings, under Settings > Connected apps: see What an administrator does.

Setting up

1. Import both files. In Postman, Import, and choose the two files. Then pick the Foldr site environment in the top right.
2. Set site. In the environment, set site to the address you sign in to Foldr at, with no trailing slash: https://your-company.foldr.cloud.
3. Register Postman as an app. Open 0. Set up and send Register this collection as an app. It registers Postman with your site as a public app (the self-registration any app can do) and saves the client_id in the environment. You only do this once per site. If an administrator has already added Postman by hand, skip it and put the client ID they give you in client_id instead. Its redirect URL must be https://oauth.pstmn.io/v1/callback.
4. Get a token. Click the collection’s name, open the Authorization tab, and choose Get New Access Token. Postman opens Foldr’s sign-in page: sign in as usual and choose Allow. Back in Postman, choose Use Token.
5. Check it works. Send 0. Set up > Who am I (getMe). You should see your own name.

The access token lasts an hour. When it runs out, every request answers 401 invalid-token: choose Refresh beside the token, or get a new one.

Working through the folders

Folder	What it does	Scope it needs
0. Set up	Registers the app, shows the site’s sign-in addresses, and getMe.	profile
1. Shares	listShares picks a share to work in and saves it as share_id.	foldr.read
2. Reading	Listings, an item, a download, a download link, search, custom fields and versions.	foldr.read
3. Making things	Makes a folder of its own, uploads a file into it, renames it, copies it, and follows the copy as an operation.	files.write
3a. Uploading straight to the storage	An upload session: open it, send the bytes to the storage, complete it.	files.write
4. Custom fields	Reads and sets a field value on the uploaded file.	fields.write
5. Sharing	Asks to share the uploaded file, and checks on the request.	sharing
6. Replacing, moving and deleting	Overwrites the file, restores an earlier version, moves the copy, and finally deletes the whole playground folder.	files.overwrite, files.move, files.delete

Run List shares before anything else. To work in a share other than the one it picks, copy that share’s id into share_id. In the same way, List a folder lists the folder named in folder (/, the top of the share, to start with) and saves the first file it sees as item_path for the other reads.

Trying changes

A self-registered app can only read, so folders 3 to 6 answer 403 insufficient-scope until the token carries the write scopes, and 403 write-not-allowed once it does but the app’s policy does not allow what the call asks. To try them:

1. An administrator opens the app (Postman) under Settings > Connected apps > Policy and allows what you want to try. Removing and replacing (folder 6) are allowed only in shares they name: name the share you’ll work in.
2. Add the same scopes to scopes in the environment, for example foldr.read offline_access profile files.write files.overwrite files.move files.delete.
3. Get a new token, and agree to the new scopes on the consent page.

Folders 3 to 6 work in a folder of their own, named by scratch_folder (/Postman playground to start with), and the last request in folder 6 deletes it with everything in it. Send them in order. If you stop part way, delete the playground folder yourself afterwards, in Foldr or with Delete the playground folder, after Read the playground folder to fetch the ETag it needs.

Some of these can’t be undone where the storage keeps no earlier versions and has no recycle bin: see Recoverability and audit. The collection only ever changes things inside the playground folder, but a request you edit can change anything the person and the app may change.

Sharing tells someone. The request in folder 5 waits for an approver, and the approver is told about it. Don’t send it on a site where that will surprise people.

Reading the results

Each request checks its own status code, and Postman’s Test Results tab shows whether it passed. When Foldr refuses a request, its problem type shows there too (for example problem: precondition-failed), so you can look it up in Errors.

Things you’re likely to meet:

• 412 precondition-failed on a change: the If-Match ETag is stale because the item has changed since it was read. Send the request that reads it again (each saves the new ETag), then the change.
• 409 operation-finished on Cancel the operation: the copy had already finished, so there was nothing to cancel. That’s normal for a small file.
• 409 no-direct-upload on Open an upload session: the share’s storage doesn’t take direct uploads. Use Upload a file instead.
• 404 not-found on a read: item_path or share_id names something the person can’t see, or something that has gone. Set them again, or clear them and send List shares and List a folder.

Using a token from somewhere else

If you already have an access token (from the worked example, say), paste it into access_token in the environment and every request uses it. The collection’s Token field reads that variable until you Use Token after Get New Access Token, which puts the new token in its place.