Understanding SAFE API flow

I’m using the SAFE email app (https://github.com/maidsafe/safe_examples/tree/master/email_app) to learn about the flow of creating, updating, and saving data with the SAFE API.

Working through the logic and I have questions along the way:

Launching email app

  • Launcher (safe_launcher-v0.8.0-win.exe) is running and I start up email app with npm run dev.

  • Launcher pop up informing me that app failed to authorize.

    • In the email app console, I see a 400 error on the POST request to http://localhost:8100/auth.
    • I add a FAIL case to front end reducer to be able to view the error object in depth:
    console.log("ACTION------------:", action);
    return { ...state };
  • Data that was sent along with the request:
       "name":"SAFE Mail Tutorial",
  • Error response in error.response.data:
{"errorCode":400,"description":"Invalid permissions requested"}
  • Testing in Postman with variations on the request but still receiving same error

Creating new account


  • Once form with email id is submitted the first thing that happens is the creation of appendable data with POST /appendable-data named with the hashed email id, which returns a handle id for that appendable data

  • The created appendable data is now saved with PUT /appendable-data/:handleId

    • How come it has to be saved now? During the POST in the previous step, is that data sort of staged somewhere waiting to be permanently saved on the network?
  • The handle to the appendable data is deleted and now we go to GET a symmetric cipher handle

  • The returned cipher handle is used to now update a structured data, in this case is a structure that holds email id, inbox, and outbox data

    • I’m gathering that the primary difference between structured and appendable data is that appendable data is meant to allow other nodes in the network to append data, while only the owner of the structured data can append data. In this case the appendable data that holds my email id can be appended with emails from other nodes, while the structured data that holds my email id and other information can only be updated by my client. Is this right and primarily the difference?

Composing email

  • Email form with recipient id, subject, and body is submitted
  • Program uses POST /data-id/appendable-data to get email recipients data id handle for the appendable data assoicated with their email id
  • Next, GET /appendable-data/handle/:dataIdHandle using the id returned from the previous step.
  • I see that the previous POST action returns only a handle id, while current GET action returns:
    "handleId": 14,
    "isOwner": true,
    "version": 0,
    "filterType": "BlackList",
    "dataLength": 0,
    "deletedDataLength": 0
  • Other than the difference in responses, what is the difference between POST /data-id/appendable-data and GET /appendable-data/handle/:dataIdHandle? Does a data id have it’s own handle while the actual piece of data that it references has it’s own handle as well?

I’m thinking that my questions may all be answered by understanding core files but my strategy here is to first learn and become proficient with this API, getting a nice higher perspective of what’s happening up here so that I can start building.

Then I’d like to spend my free time learning the core files and the the systems concepts associated with them.

Thank you for your help.


@hunterlester, can you try with the launcher version 0.10.0 .

Also please note that, we are changing our approach in API exposure. We are planning to provide language specific libraries that can be used by the application to connect with SAFE Network.

Instead of launcher, we will have an Authenticator app that will manage the permissions granted by the user. You can read the RFC to know more on the new approach.


Thank you.

Oh and because developers don’t get enough love, I want to say thank you to you and to @Shankar_S for the email app. It’s such an effective educational tool for me right now as I learn.This is the ideal app to help onboard new developers, coming from the perspective of a novice like myself.