Assorted questions about the API

Development
1

Okay I have a couple of these and they’re kind of random so forgive the disorganization. I’ve been reading and rereading over the API documentation trying to make sense of it but am struggling to make logical sense of it so could really use some help.

  • Why are they in different languages? Shouldn’t the devs just pic a standard language or languages to create the examples in so that it’s easier to compare and contrast? Some code examples are in json, some are in node.js, some seem even to be in something else entirely but the point is shouldn’t they be in the same language, preferably both?
  • There seems to be 2 of everything, or multiple copies of everything, which just makes things even more confusing. There’s a POST and a GET for /auth without adaquate documentation on the difference thereof. I thought /auth was designed to give you an authorization token or something? I’m still a bit fuzzy on how that works but the point is if it’s function is to give you an authorization token why does it need a GET and POST function? But it’s not just that. It’s that a lot of the commands are similar, or have minor differences like that. I feel like I need like a flow chart or something to understand this API it’s so complicated.
  • How exactly would the program flow work if one wanted to create a simple program to work with SAFE? So say a Hello World program that prompts the user to upload a picture that is then stored on their SAFE drive and displayed by the program. Simple but how would it work?
1 Like
2

Really good input for the documenters @Blindsite2k

I think you struggling through this is very valuable - for you and the project. I’ve been doing a bit myself lately so I know what you mean.

Keep this feedback up if you can, and to tackle particular roadblocks, grab a some of the existing code (from @cretz or from safe_demo etc), try modifying it, and then post detailed "help, I’m stuck here! " questions and I think you get a response.

A way to get feedback right to the coalface is to post comments like this as issues on the github repos - if you can find the repo for the particular bit of documentation/API. You’ll often get a direct response there to a question like those you have about auth. I don’t know the answers as I’ve not been looking at that level yet.

I’ve been doing this with the safe_launcher and it has been painful because I only know basic javascript, and have been struggling with AngularJS and node.js, and trying to understand the very complex callbacks used to call the SAFE API. Then trying to rework it with Promises which are also new to me, and so quite weird. I’ve never done async programming. I’m just poking around in order to learn - much more fun than moderating :wink:

So like you probably, I feel like the baby in that UX video by Aral Balkan that someone posted! :slight_smile: Keep going David, it feels to me like you are making progress, and it touches my heart. :joy:

2 Likes
3

POST and GET are http methods , used during the communication between an app and the launcher, which happen to use the HTTP protocol to talk to each other :
Hypertext Transfer Protocol - Wikipedia

in the /auth example they are used to do 2 very different things : POST sends an authorisation request to the launcher, in return if you are a nice app, you are returned a token, a key and a nonce for future use. GET sends a message to CHECK that the previously returned token is valid.

I presume you could try to first read about HTTP , and REST APIs.

A good start could be : HTTP Methods for RESTful Services

or HTTP - Methods

Once you get these concepts, the MaidSafe API documentation makes much more sense .

Look at the top of /auth , for instance.

You will learn that : the GET method for the auth scope : is used " To check whether the authorisation token obtained is valid.
The Authorization header must be present in the request. "

Now look at the POST method : /auth , and you find the purpose of the POST method in the auth scope.

and so on, for the various methods in auth, nfs, dns, etc etc

As for examples in various languages, I think it is a good thing - reading the various examples, if you try to look at things broadly, even if you don’t master each language individually, helps a lot to get the underlying concepts of what happens during the “discussion” between the app and launcher.

While I do agree that the API documentation is quite sparse so far, I suppose it does it job, and that it would be very nice if some people write TUTORIALs and Howto’s in paralel.

I hope this can help !

3 Likes
4

Hi, I don’t know much about SAFE yet but your first two questions are general so I’ll try to help.

JavaScript, JSON and node.js are not three languages. They are all JavaScript.

JSON, short for JavaScript Object Notation, is a data serialization format, so it’s used to save data to the harddisk or send it over the network. It is just the syntax that JavaScript uses for objects, it was so nice and lightweight that it was then used in other languages as a serialization format as well. If you know JavaScript, you have no problem understanding JSON because it is JavaScript.

node.js is also not a language, it is three things. First, it uses Google Chrome’s V8 JavaScript engine to allow you to run JavaScript code as desktop/server applications as opposed to be running just inside a web browser on a website. Second, it’s a library, a set of commands to work with the file system and other things like that which aren’t part of JavaScript itself because normally (without node.js) it has no access to such things, it’s restricted to the browser. And lastly, it is, or rather allows you to easily create a web server with JavaScript, that is it’s main intended use but it’s been used for much more nowadays, command line applications mostly, developer tools. And with Github’s Electron you can even use it to create graphical desktop applications like the SAFE launcher and the SAFE demo app.

As for the multiple copies of everything in the api (I see someone else answered while I wrote this so feel free to skip this, but maybe it still helps), the GET and the POST and the DELETE, that is what is called REST, or a RESTFul API (you should have no problem finding a lot of information about this when you Google it). It is a convention used to create a (usually) HTTP based network API, most of them today are RESTful so having this convention is neat because then you only have to learn one system and understand the basics for all. GET is used when you want to retrieve data from an API, POST is used when you send data to an API, These are called HTTP verbs or HTTP methods.

The difference between GET /auth and POST /auth is explained at the very top of the API docs. POST initiates the authorization to get the login credentials, and GET wether the authentication credentials you have are valid (maybe you cached them and want to check if they are still valid or if you need to authorize again). DELETE /auth basically logs you out.

6 Likes
5

my guess :

  • program sends a auth POST request to the launcher , with valid app info
  • launcher returns a TOKEN, a key and nonce
  • program is happy, it can continue :
  • program asks the user for a file to be uploaded
  • user types a path / clicks a button / whatever method to feed the program with a picture
  • program encodes the file info using the key and nonce
  • showing its valid token, the program sends a nfs : file POST request to launcher with the path for the file INSIDE the safe network , this will CREATE an EMPTY file in the safe network
  • launcher returns “200 OK” response , everything is fine so far
  • program encrpyts the image using the key and nonce
  • showing again ts token, program sends a nfs: file PUT request to the launcher , with the encrypted image data and the path to the file that was previously created - this will UPDATE the empty file with content
  • launcher sends 200 OK, good ! we are happy

( at this point the coder wonders why he didn’t display the original unencrypted image , but he is in a playful state of mind and goes on )

  • showing the token, program sends a nfs: file GET with the file path
  • launcher returns a 200 OK, and the encrypted image data
  • program decrypts the data using its key and nonce
  • program displays the image
  • program sends a auth : DELETE , so that the token is destroyed
  • launcher sends 200, then forgets about progam

pfew !

1 Like
6

Correction JSON and node.js are based on javascript. But both JSON and node.js have their own syntax and language. They are not the same. How the syntax changes is the key. One could argue it’s all just varying degrees of javascript with some tweaks here and there but it’s the tweaks to the code that make the difference. Whatever one calls it one still needs to know how to correctly write it in order for the program to function.

@nice

Okay that’s a lot of steps and I’d need code examples and a bit of help to get my head around that. I’m just saying that up front. Also what exactly is “200 OK”? Also I used the example of an image because I wanted a simple task to perform and displaying an image should be fairly simple.

7

200 is an HTTP STATUS response from the launcher., just like 404 error when your browser asked for a page that doesn’t exist.

when you send a request using HTTP, your correspondant sends you back a STATUS, they tell you “its all good”, or “we don’t have that in stock” , or “404 , page not found” , or… plenty of funny stuff

The Safe API documentation shows us what code they use, and in what cases, and how to handle them.

I would really advise trying to grasp the http methods idea first. Then you can dig into how to apply this to safe. Look at the tutorials I linked in my 1st reply, or find plenty of these in internet :slight_smile:

8

I have used node.js and JSON daily for years, I have yet to see a single difference in syntax, but if someone has an example of such a difference please correct me, maybe I was just lucky to never run into that :slight_smile: You do of course need to learn the new functionality node.js brings with it if you want to use that new functionality (anything else is still the same though). JSON is a subset of JavaScript so to read it you don’t need to learn anything, but to write it you need to know what parts of JavaScript it doesn’t support. Still, not a language, it’s a serialization format as I said. Wikipedia calls it a data interchange format. Java would be a different language. Or to make it more SAFE specific, Rust is a different language. But as long as you do understand that that’s okay, I just thought this misunderstanding from you might be one of the main sources of your trouble to understand how the SAFE API works.

1 Like
9

This is an important point to understand. Node is a runtime environment. Much like .net is for the languages that run on it. The javascript you write is executed by Node, or put another way, Node allows you to execute javascript code on the server (the computer that is running node).

There are lots of node libraries (javascript code) that allow you to do all kinds of things. For example, Express is a library to handle web requests and responses.

10

Just to add, node is not just javascript on server any more. I found that quote confusing for a while.