New Devs SAFE Launcher API Tutorial

WhiteOutMashups · August 30, 2016, 12:43am

Hopefully this turns into a joint effort

EDIT: ADDED JSON SECTION

Been researching more, to be more self sufficient in creating my SAFE apps (relying less on hiring out tasks), and very base level of developing SAFE Apps starts with SAFE Network’s REST APIs, in my opinion. So I am beginning by creating this intro to it all. Here we go!:

API = Application Programming Interface

What is an API? It’s a bunch of easy tools & commands that developers have created to make it easy for your software to communicate with their software.

REST = Representational State Transfer

What is a REST API? It’s the most used type of API. Google’s, Twitter’s, Facebook’s & other groups APIs all are examples of REST APIs.

How does it work? Very much like a server-based website. Client requests the API, and information is sent back over the HTTP protocol.

Can I see a quick example? Sure! Instead of viewing YT’s regular FB page (at YouTube), go to graph.facebook.com/youtube to create an API call to facebook’s servers. It will return a response, over http, in JSON format (more on that below). *May give an error if you aren’t properly logged in / authenticated, as common with APIs.

JSON = Javascript Object Notation
Super simple thing. It’s only these 2 things: { “key” : “value” } that’s it!!! Best way to send requests for data (or any kind of info), in a super streamlined, efficient format.
Used in APIs alot so you can ask for info easily, like a YouTube API request where you ask for a video key “url” and value : “yt.com/WTf5g”
Best part, it’s JAVASCRIPT (J.S.O.N. the JS = Javascript), so it works perfectly with it. Integrates perfectly. Great news for web apps, where JS is the primary language for all the programming.

Looks like the next step will be simple step-by-step tutorials in various languages, where we execute API commands to the SAFE Network.

WhiteOutMashups · August 30, 2016, 12:54am

Actually, I think the most important is just creating API “calls” using the bare REST API. Then, once people understand that, step #2 should be using “wrappers” for other languages (JS, Python, etc).

bluebird · August 30, 2016, 9:23am

I’ll fire up Wireshark some time today and see what packets are emitted by the launcher at the start, which will show the protocol.

DavidMtl · August 30, 2016, 11:14am

There is no such thing as “bare REST API calls”. In order to communicate with a RESTful service you need a communication protocol. In our case we use HTTP. But you can’t really do bare HTTP calls either. You need a programming language and that’s where you choose Javacript (web or node), python, rust, c++, etc. Maybe I didn’t understand you correctly but it seems like you think these programming language are just wrapper over something purer that you should learn first.

My advice is pick a programming language you want to learn. Search how to do an HTTP request and set it up to make the call to a RESTful service. Or pick the code I gave in the other thread and add new calls for all missing features. That should get you started.

You really don’t need to fire up Wireshark in order to see the bits going in and out, that’s way too much overkill for starting playing with the SAFE API.

Start small.

JBishop · August 30, 2016, 2:06pm

And let’s agree where we are going to continue this …

Three competing topics, this one:
New Devs SAFE Launcher API Tutorial
Another started earlier:
‘Hello World’ SAFE App Example
And the one in the Safenetworkforum also posted in today:
SAFE Network Forum - Help making tutorial apps

WhiteOutMashups · August 30, 2016, 9:07pm

Which shows the crazy amount of demand for a super simple tutorial.

Let’s get this done then

WhiteOutMashups · August 30, 2016, 9:11pm

Gotcha. First time working with them. Thought it was more of a language of it’s own, now I see it’s more of a set of tools that you use with any language.

WhiteOutMashups · September 5, 2016, 3:47am

EDITTED OP to add essential knowledge section on JSON.

Thinking of turning this into a little website or start a blog post of it or something.

Want it to be a resource for brand new devs to get the basic knowledge to get up and running on creating apps for SAFE in the most streamlined way.

ben · September 5, 2016, 6:33am

Well, with REST (over HTTP(s)) you could always use curl to do stuff . Which for a tutorial for developer isn’t even that bad, as it is “language agnostic” and simple to decipher (and something no one will copy-paste!). They do it at square for their docs, and it is awesome.

bochaco · October 3, 2016, 3:11am

I’m going thru the SAFE Dev tutorial and started to play with the Launcher API using Postman; I was actually wondering if anyone has created a Postman collection?
I can otherwise share the collection I’m creating as I study the API, it can perhaps be kept in a shareable location/repo.

happybeing · October 3, 2016, 10:49am

I hadn’t even heard of this and AFAIK it hasn’t been mentioned by anyone on these forums, so yes pleeeease! It looks great and providing something to help others make use of it would be great.

Thank you

bochaco · October 3, 2016, 5:08pm

Ok, I will work on adding more requests to the collection and share it here in the next few days.
Last night I managed to send an email (compatible with the sample email app) using just Postman

WhiteOutMashups · October 3, 2016, 5:31pm

Postman is great, that’s a great idea

Almost forgot. I’ll play with it too

bochaco · October 3, 2016, 10:50pm

I have a Postman collection ready to share with you which contains the requests necessary to send an email, but I don’t know where I should upload it, can you please advise?

dirvine · October 3, 2016, 11:04pm

A github repo probably would work best, perhaps? Nice work, postman is superb for testing API’s and trying stuff out like that. Nice one

bochaco · October 3, 2016, 11:15pm

Thanks @dirvine. Do you mean within MaidSafe · GitHub or my own repo? (I just don’t how you usually handle something like this, It’s ok for me either way)

dirvine · October 3, 2016, 11:27pm

If you create your own repo that’s cool. We must at some stage collate links to all of these as we go along. I am not sure should we fork them all under a maidsafe community repo and have folks, including us update the code when the API’s are maturing etc.

Anyway your own will be fine for sure. I may start a thread about some kind of way to collate all of these and seek options etc.

WhiteOutMashups · October 3, 2016, 11:27pm

Sounds like he meant just make a repo

EDIT: TIL MaidSafe only hires ninjas

bochaco · October 3, 2016, 11:28pm

Ok, cool, I’ll do that.

EDIT: I just uploaded it here: GitHub - bochaco/safe-launcher-api-client: SAFE Launcher API client

I’ll be adding some explanations of how the requests work and how the environment variables are used for each of them.
For the time being this is how it can be used:

Import the collection and the environment variables into Postman
Set the recipient’s email id in the “recipient-email-id” environment variable
Execute the requests in the following order:

POST /auth
GET /auth (optional: to verify it was authorized)
GET /appendableData/handle
GET /appendableData/encryptKey
POST /immutableData (edit the body beforehand, if you want to change the email’s content. Note the time is calculated automatically)
GET /immutableData (optional: to verify the DataMap’s content)
PUT /appendableData/handle

ben · October 4, 2016, 7:44am

I want to make clear that I am not a ninja – neither do I believe any other team member would say that about themselves. While MaidSafe insist on hiring qualified people, most people describing themselves with these terms (“ninja”, “guru”, “jedi” or “rock star”) usually are not. Quite the opposite, from my experience in this field I’d say that the more experienced the developer, the more humble they become.