Help making tutorial apps

Development
#26

The wrappers aren’t really needed because the API is very simple.

Granted, it isn’t easy to use until you understand how REST works, and how to setup the parameters and handle the results, but the wrappers are a convenience that will get in the way of understanding the API until you understand the language the wrapper is written in.

For the RemoteStorage.js port I decided not to create a wrapper and just call the REST API directly because I didn’t know JavaScript well enough to design a decent wrapper, and the existing wrappers were not suitable since I’m not using node.js, but just JavaScript.

My code is clunky as a result, and I’d like to refactor it at some point as I’m getting a bit more skilled, but it works.

I think there was one pure JavaScript wrapper, but I didn’t want to be dependent on someone maintaining a wrapper I don’t understand when the SAFE API changes. Also, like you, I wanted to learn about REST and the SAFE API :slight_smile:. This paid off this week because I managed to upgrade from the 0.4 API to 0.5 in less than a day, much to my surprise.

If you want to look at some pure JavaScript code that includes /auth as well as creating and reading files and directories, take a look at safestore.js which is colour coded by github. Or clone the repo and load it into an editor or IDE that understands JavaScript.

Start by looking at safestoreAuthorize(), which obtains a token using the /auth API.

Then look at the other places I call the API - hint: search for calls to _request.

Also, if you look at the _request() function itself, notice how it inserts the token obtained by safestoreAuthorize() into the headers for each HTTP request.

You can ignore most of the code around the calls to the API and just look at how I call each API by setting up the call to do the HTTP requests, and how I interpret the results returned by them.

Since I’m just using pure JavaScript and built in browser HTTP support, there is not much you need to research to understand what each call is doing. On the other hand, my code is slightly different from the MaidSafe examples because they are using node.js functions in some places (which I find confusing because I don’t know node.js, and have had to figure out how to do in pure JavaScript).

I don’t have much time to explain what the code is doing (and most of it is irrelevant to you seeing how I use the SAFE API) but will try to answer questions that are not too involved - don’t expect instant replies though because I’m juggling several things ATM (not software) :slight_smile:

2 Likes
#27

@Blindsite2k reading along with you, I think I hear opportunity knocking:

At the time I did bookmark this and also @happybeing’s reply:

Because I for one would very much like to have a go at this, build something and then trawl trough the old and the new forum for any of said morsels and list and link to it, back and forth, also because of the technical challenge of not doing this all by hand.

But in lieu of the full Monty - indexing and cross-referencing it all - for now a tiny bit of aggregate cut-and-paste from November last year and onwards:

What’s holding me back - next to not being native English-spoken - is expected level of expertise here, of one addressing the other? Idea, maybe a form of acting as Dumb and Dumber will do it, thereby implicitly shutting out all forum visitors not wanting to be seen as one.

But would there still be an audience? At least one consisting of you and me it looks like. So what if we turn this around and we start to tutor ourselves, duly reporting about the progress we make, if any.

In fact the opposite of the new dev.forum, although I think the serial buzz of the Discourse format maybe distracts from a story as it develops when one struggles along. A blog-like presentation coupled with for instance this fairly new annotation-facility called Hypothes.is (pull upper-right-side tab) would be preferable.

The latter also because it’s groups-option enables different levels of (private) discussion and reentrance of the pro’s as mentor?

So @blindsite2k are you game? If yes then we’ll probably need some initial help with a modest request for resources?

In the meantime, maybe this here about Node.js and JSON can help you in the right direction?

3 Likes
#28

@JBishop I’ll have to look into the projects you mentioned but as for collaborative self education yep I’m game. Also posting tutorials and help files as we learn. What is your native language? I might be able to round up some linguistic help for you. Also have you considered documentation translation?

1 Like
#29

Ok! So collaborative self-education it’ll be. You jump-started this already nicely, there’s an immediate goal, “Hello World” as specified by you in your OP and enough advice to chew on including this additional write-up.

Next what, any other preparations to make? For example continue here in this thread, a separate topic to ponder things or a little more ambitious, our own webpage here in the neighborhood?

This language thing is the other way round, Consider myself adept in Dutch and find myself out of that comfort zone when it has to be in English but I’m used to pouring over English technical documentation of all kinds albeit not yet for Node.js.

1 Like
#30

For now we can continue here. We might branch off into another topic if we need to but for the time being we’re still rather focused on creating a simple tutorial and understanding the API. Maybe in time after we gather enough data and write up enough tutorials we could develop a website but at this point we can’t even figure out all the pieces of the api or how to use it to connect properly yet let alone create a hello world app. So that’s kind of beyond our scope at this point.

Well 1. Whatever we come up with you could translate into Dutch. Also there’s ton of docummentation on the maidsafe website that could probably use translating. Translation = a bigger audience to draw from. More developers and users. 2. You could always look into sites like www.duolingo.com to help you brush up your English. I know Dutch is one of the languages they provide. English/Dutch Dutch/English. You seem pretty fluent to me. So maybe it’s just a case of expanding your vocabulary. Maybe just try doing some reading and such.

#31

Okay after reading this

And after doing some thinking after a few days here are my musings.

Data cannot just appear in your database. It has to be moved there from somewhere else. Which means it has to move along a connection of some sort. Much like a phone that will not work and get a dial tone unless it’s plugged into the network via a phone cord you need to plug your app into the API via a line of code.

As near as I can figure this is your phone cord.

http://localhost:8100/auth

or at least it is in the case of authenticating. You send data there and the API then sends data back along that connection into your database. I may be wrong but it appears that is a created tag and is part of the API system that is expected by the API to signal the return of an authentication token.

I’m not quite understanding the specifics of the nodejs exactly but the logic seems to be post = status code 200, which would seem to infer the assumption the app got authenticated. The rest is if else statements to handle cases where it would have failed in the cases of 400 and 401.

I think this will come down to playing around with code in javascript and juryrigging something. It’s going to look god awful most likely but that might just be the only sollution.

#32

Google ‘rest api’ and a lot box this will make more sense. They use HTTP status codes to confirm status, much like web browsers do.

As a developer, you get used to sifting through this stuff, connecting dots from previous experience. There are narratives about all the technologies used for the safe api, but be assured that it will be familiar to almost everyone who works will web services.

For those who don’t wish to go that deep, wrappers will become available, to allow simpler integration, most suited to the chosen language.

The point of the REST API is not to make it so simple that anyone can code for it. The point is to easily allow integration with as many languages as possible and allow others to wrap it with something higher level.

1 Like
#33

OK, let me try a few things - at this point we don’t know how much the other knows about anything?

http://localhost:8100/auth

What maybe could help you feel at home, this looks like what you must have asked from any plain web-server about a million times:

http://thisorthat.com

The following is tentative about what you’ve encountered before in this ‘field’ but I’ll do it anyway. if only for someone else not in the know here, list a few variations:

http://www.thisorthat.com
http://www.thisorthat.com/nowwhat
http://www.thisorthat.com/index.html
etc.

Let me ask, did you in this case also wonder how FireFox or what you use did get what you typed in or clicked on?

If that is the case then maybe we will have to ask and get that filled in for a bit too: how does the browser interact with Linux, Windows or OS X but for now we can only hope you can live with what works as it stands ;o)

Next, they (you, me) leave the ‘port’-number for these web server-requests out if it is ‘standard’ port-number 80, so

http://www.thisorthat.com

Done by the book would then be:

http://www.thisorthat.com:80

And a slightly more involved structure again

http://www.thisorthat.com:80/nowwhat

Often it is OK to leave out “www.” especially if it is not about webpages at all with this particular server

http://thisorthat.com:80/nowwhat

If the port number is not standard then you will have to tell yourself or your Hello world-thingy explicitly where to go, for example you as a developer can in such a case opt for a port with number 8100

http://thisorthat.com:8100/nowwhat

Now this all starts to looks a lot like what you have to do when you want something from a server if this server happens to be a server on your own computer? In which case they often use

http://localhost

Which sums it up nicely, and local and host, could be a server doing its service on behalf of the Safe network …

Cliffhanger is of course, what happens when you open the browser on your own PC to

http://localhost:8100

Would be too easy if you got “Hello World” back ;o)

#34

Well this is why I’m using the phone metaphor. Federated phone protocols work regardless of whether it’s a cell, landline or whatever phone company or particular brand one is using. Not to mention learning to phreak isn’t exactly a walk in the park.

I guess what I’m wondeirng is what signals is the API listening for from the various languages? What patterns do the languages need to send down the line for the API to return various signals? Similar to how you can manually send different Hrz down the phone line via audio signals but it’s easier just to use the “wrapper” of a touch tone phone. You can use different programming languages to create these signals but you need to know specifically what the API is listening for before you can send them. Is the API listening for a payload json file? Is it listening for a tag? I know these might sound like stupid questions but if we’re writing for different languages these seem like important distinctions for data being sent back and forth down the pipe.

#35

This is what REST provides. So perhaps like this

REST == Mechanism to communicate (Get Put Post etc.)
JSON == representation format of data communicated over REST (in SAFE)
API (for SAFE) shows the specific JSON format of messages communicated

On top of all that you can say any programming language that respects these elements works. so this is perhaps where the language metaphor you are looking at comes in, if that makes sense.

3 Likes
#36

@happybeing Okay I’m trying to read your code but gah can’t find where you are defining variables. And half your code is commented out?

this.safestoreAuthorize(this.rs.apiKeys[‘safestore’]);

Okay first question. What is “this”? You use it a lot and I’m not sure if it’s a javascript function I don’t know about or a variable that’s weirdly defined. var self = this ??? What does that mean? Second question where are the apiKeys defined? I searched the entire code but couldn’t find a definition. More questions of a similar nature. But let’s start there.

1 Like
#37

In many languages, “this” means current object. so say object is a square you could say “this.side.length = 2” You generally have a var that is an “instance” of an object so “var my_square = square” then this is a pointer to my_square which you can refer to the object currently in use. So methods in the object square point to this, but if you have an instance of the object “this” still points to “your” instance of square.

1 Like
#38

…you keep changing what you’re asking for…

Mr. Irvine just gave you links to REST.
That’s what’s happening under the hood.

You replied with, “no, I just want to know enough to write a hello world app.”

So the next person gave you wrapper tools to skip all that and just code a simple app in python.

Now you’re asking for what’s happening under the hood again… That’s REST…

Please decide…

#39

@Blindsite2k the “signal” the API is listening for is simply http. It’s the same protocol your browser.
It defines a set of verbs (GET, POST, PUT, DELETE, HEAD …) a mechanism for sending and a set of headers. One of them being Content-Type that tells the recipient what will come down the line.
Http also defines a set of status codes, 2xx being “all is fine”, 4xx being “you messed up” and 5xx being “the server messed up / is on fire”.

That’s how it becomes language agnostic, http simply cares that you send well formed requests over the line (usually over tcp/ip)

The api spec then tells you what endpoints (/auth, /nfs, /dns, …) are available and what type of request body to pass in and what type of response to expect back.

Thus what you need to talk to the api in any given language is a means to speak http and pass some json along.

The reason for building on top of the http client facilities in your language + platform of choice is so smooth out some of the wrinkles and make it fit better in the given language.

Simply taking the first “http basics” link from google https://www.ntu.edu.sg/home/ehchua/programming/webprogramming/HTTP_Basics.html should be sufficient to give you enough information to understand how it ties together.

1 Like
#40

Which I can’t understand, but I am studying anyway. But that will take a whole lot of time.

And I explicitly stated that I can’t really write worth a damn in python. I am a bit decent with javascript hence my efforts in understanding the code so I can use the API with javascript and json, which I am literate in. Makes more sense than learning an entirely new language that I don’t yet know how to code in.

Yes I know it’s rest but the point is how does it work and more to the point how is it relevant to what I need to code? If I have t opend a month or 3 learning REST and HTTP just to make a Hello World app that seems a bit excessive. I’d much rather just know what signals the API is listening for and need to be sent down the pipe in order to get the desired responses and what flags to listen for. Isn’t that the point of having an API?

#41

Thanks for the link. I’ll read through this but goddess I think this is going to require coffeee. Okay so HTTP is the signal so how do I now use HTTP with javascript and json correctly and get it all passed and coded? Okay going to brew some coffee and read this.

#42

@Blindsite2k the “how do I http” question depends on your chosen runtime + libraries.

For node you got the examples already in the documentation.
If you’re doing client side / browser based work then you either use raw XHR or usually cleaner and more portable use whatever http abstraction your framework of choice comes bundled with there’s a jQuery tutorial or maybe Angular?

it’s really no more complicated than that.

1 Like
#43

Oh lord I haven’t really gotten into jQuery or Angular. Okay MOAR reading.

#44

Adding to that, JavaScript is especially fun in this regard: other languages (say, C++) have special constructs that represent methods/member functions so that it only makes sense to invoke them on particular objects. In JavaScript “member” functions are actually just normal functions that happen to be invoked as members of objects. So, in JavaScript this is a special identifier within a function body whose meaning depends on the “context” of the function call, so it is the object that the function is a member of if it’s invoked as a member of an object, undefined or the global window object or something like that if the function is called “loose,” or a custom object if the function is invoked indirectly via .call or .bind (because JavaScript functions are also objects and have their own methods). For instance, here’s some code and what I get as output when I run it in my browser:

class Type {
  member() {
    console.log(this);
  }
}
function free() {
  console.log(this);
}
let obj = new Type();
obj.member(); //< obj
free(); //< the global Window object
obj.member_free = free;
let free_member = obj.member;
obj.member_free(); //< obj
free_member(); //< undefined
free.call(2); //< Number object with value 2 (not just 2, because this has to be an object)

All of the details of how this works are better explained by the MDN page on it.

The upshot of all of this stuff about how JavaScript handles this is that this takes on a new value for each function invocation, whether it completely makes sense or not, and this makes programming with closures interesting. In C++, when you define an anonymous function inside of a member function, you can just capture this and it will refer to the same object as in the member function (though that object might no longer exist when the lambda is called if the code was written incorrectly, which is what makes capturing by reference/pointers in C++ exciting). JavaScript, on the other hand, will come up with a new value for this when the anonymous function is called according to the same rules sketched above, so even though it would intuitively look like it ought to capture the this value from the enclosing function, it doesn’t. Doing var self = this is a way of getting around this problem, because self is captured normally by the enclosed function and so it doesn’t have the problem of referring to the wrong thing when that function is called like this does.

Also, the new version of JavaScript (ES6) has a new way of specifying lambdas called “arrow functions” which are much more succinct than normal JavaScript function declarations but which also have the nice property of automatically capturing this like one would expect them to in this case. I’m not sure what level of ES6 support one can expect for browsers running SAFEsites, but if it is supported these are clearly a much less confusing way of handling creating anonymous functions inside of member functions.

2 Likes
#45

Uh okay about 3/4s of that went right over my head sorry. Also I’m not sure the code you’ve written is javascript. I mean it kind of looks like it but it’s weird. Looks more like node.js but maybe I’m just ignorant or something.