Calculating API calls
Below, you can find some scenario examples to help you estimating the amount of calls you will need to send to the Space Blocks APIs for your application.
A word about authentication
Calls against the Space Blocks API needs to be authenticated with a Regular Access Token. Access Tokens are issued by the Token Manager API and can be re-used across multiple calls. Requesting an Access Token at the Token manager also counts as 1 call. Space Blocks Access Tokens are valid for 1 hour.
Frontend applications can communicate with Space Blocks directly using an Impersonated Access Token, which also issued by the Token Manager. Impersonated Access Tokens are bound to one subject (e.g., one user) of your application and can also be re-used across calls but not across subjects. The flow of requesting an Impersonated Access Token goes through your Backend, which then talks to the Token Manager API. Issuing and Impersonated Access Token also counts as 1 call. Impersonated Space Blocks Access Tokens are valid for 1 hour.
Sample scenarios
User wants to see all their folders
User Bob logs into your application and wants to see all folders he is allowed to see on one view.
➊ Your Frontend requests all folders where Bob has access to at your Backend
➋ Your Backend requests all resources of type folder, where Bob has the read permission on from Space Blocks
➌ Space Blocks responds with a list of folder IDs
➍ Your Backend queries your database for all folders with these IDs
➎ You Backend returns the results to your Frontend
API Used: ListResources
Scenario: List resources with permissions
Total # of calls to Space Blocks: 1
Check, if user is allowed to delete a file
User Bob wants to delete a file, and you need to check with Space Blocks if he has the permissions to do so. For this, in the Delete logic of your backend, you can check Bob’s permissions on the file he wants to delete with Space Blocks.
➊ In your Frontend, Bob wants to delete folder Foo and sends that request to your Backend
➋ Your Backend checks, if Bob has the delete permission on a folder with ID Foo at Space Blocks
➌ Space Blocks responds with true or false
➍ If the response it positive, your Backend deletes the folder on your database
➎ You Backend returns HTTP Status code 204 (No Content) or 403 (Forbidden) the your Frontend
API Used: CheckPermissions
Scenario: Check permissions
Total # of calls to Space Blocks: 1
Check, which options to show to the user in the UI and double-check the permission in the backend
User Bob opens the Context Menu of a file in your application. You need to check, if a certain option (e.g. "Rename file") should be visible. In this case, your Frontend can ask for a list of permissions that Bob has on that file, to craft the Context Menu UI accordingly. You should additionally double-check the permissions on your server side, to make sure the user is not able to perform actions they are not allowed to.
➊ Your Frontend asks Space Blocks directly, which permissions Bob has on file Foo
➋ Space Blocks verifies Bob’s permissions to list permissions and returns Bob’s permissions (based on which your Frontend shows or hides the “Rename file” button)
➌ In your Frontend, Bob wants to rename file Foo and sends that request to your Backend
➍ Your Backend double-checks, if Bob has the rename permission on a file with ID Foo at Space Blocks
➎ Space Blocks responds with true or false
❻ If the response it positive, your Backend renames the folder on your database
❼ You Backend returns HTTP Status code 200 (OK) or 403 (Forbidden) the your Frontend
For communicating directly with Space Blocks, your Frontend needs an impersonated Access Token, with should be issued by your backend.
APIs Used: ListPermissions, CheckPermissions
Scenario: List permissions
Total # of calls to Space Blocks: 2
User wants to see all files within a folder
User Bob opens a folder in your application. The folder contains multiple files. You need to find out, which of these files Bob has read permission on.
➊ Your Frontend requests all files from folder Foo at your Backend as user Bob
➋ Your Backend requests all resources of type file, where Bob has the read permission on from Space Blocks
➌ Space Blocks responds with a list of file IDs
➍ Your Backend queries your database for all files in folder Foo with the file IDs as a filter
➎ You Backend returns the results to your Frontend
API Used: ListResources
Scenario: List resources with permissions
Total # of calls to Space Blocks: 1
User wants to give access to a folder to another user
User Bob wants to give user Linda read-only access to a folder in your application. For this, you need to make sure to have a role, which includes only those permissions, that readers can have and make Bob assign this role to Linda on the folder he wants to share.
➊ Your Frontend, user Bob requests at Space Blocks directly, to add Linda with the reader role to the members of folder Foo
➋ Space Blocks verifies Bob’s permissions to update the members and confirms the change
For communicating directly with Space Blocks, your Frontend needs an impersonated Access Token, with should be issued by your backend.
APIs Used: UpsertResourceMembers
Scenario: Assign roles
Total # of calls to Space Blocks: 1