Help making tutorial apps

[hintofbasil]

Hi again Blindsite,

Reading through the comments I have a few things to chime in again.

The token is a string. An example one I generated is "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6IkFFbXNmSHJJU2dCL1JFM2I3WTlzNnZaUHUyNk1yWlN0VkhwWmJpOHY0OVE9In0.KvTVpebO-kR29SIa96qvxcbaZ2FbhrG0wU4ve42eRnQ".

You also mention that you think beginners will struggle to understand the API. I believe this is actually OK as this is where API wrappers come into play. We have a number in the works (most of which are outdated and coded for API 0.4). These are designed to simplify the API and make it useable in a different language. Below is a sample from my wrapper:

s = Safe('Sample application', 'v0.0.1', 'Author', 'namespace')
if s.authorize():
    print('We are authorized!')
else:
    print('Failed to authorize)

Hopefully you find this much easier to read as it removes the requirement to understand REST, Javascript, NodeJS etc.

The only knowledge required to understand this is Python. Obviously this will require it’s own documentation, which I have begun work on, however it should be much easier for a Python programmer to understand the Python documentation, especially with the removal of REST code.

If we can generate an API wrapper for each language understanding and using the API becomes much easier. This might sound like a lot of work but it’s a very common approach to this problem, as the base API must remain language agnostic.

[Blindsite2k]

I generally like to know whats going on under the hood but for practicality’s sake yes having api wrappers for each language that could just be copy/pasted into your app and then have your data plugged directly into them would be very useful. I don’t actually find the wrapper easier to understand because I’m not seeing where s is getting the “authorize” function from. But I see how the wrapper would function. Preprogram the if else statements needed in the API into functions for various languages that can then be imported into variuos apps. In my case it would be javascript or something similar.

[drunkcod]

@Blindsite2k I guess you’ll need to decide on which path to take here.
If you wan’t to quickly use the api and build apps usually going with already developed wrapper is by far the quickest route and isolates you from the underlying concepts.

If you do want to know what’s going on well then you’ll simply have to read up on all the constituent pieces and there’s really not feasible for anyone to create a “tutorial” that goes through all of them in enough detail to be both useful as a quick start and to educate about everything from json to http, mime types, asynchronous calls, some implementation language and doe something useful at the same time.

In all fairness the Launcher API is very small and requires only basic understanding of how to make http requests and serialize and deserialize some json. There’s plenty of tutorials and samples on that available
that should get you to a point where starting to exploring the api should be a breeze.

If you’re struggling with some particular part of it simply use Postman Postman - Chrome Web Store
there you can build your requests simply and it even have the ability to generate code for many different platforms to make the equivalent request from code.

[hintofbasil]

@Blindsite2k

Preprogram the if else statements needed in the API into functions for various languages

Yes, that’s exactly what it does! It hides the complexity from the average user.

Every programmer does this. I’ve not personally read the code for Pythons print(). I simply read what the function does. At some point you have to say “That’s enough detail for me” otherwise you’ll find yourself reading low-level compiler code which is almost completely irrelevant to what you’re trying to achieve. Finding the “that’s enough” point is tricky though.

@Blindsite2k

I’m not seeing where s is getting the “authorize” function from.

The authorize function is what I wrote. (Actually I called it authenticate. Woops…) You can view the raw code if you really want - but the defeats the point of a wrapper. All you need to know is that calling s.authenticate() attempts to authenticate with the Launcher. The actual implementation shouldn’t be a concern. Just like the actual implementation for print() isn’t a concern for me.

[Blindsite2k]

@hintofbasil

Every programmer does this. I’ve not personally read the code for Pythons print(). I simply read what the function does. At some point you have to say “That’s enough detail for me” otherwise you’ll find yourself reading low-level compiler code which is almost completely irrelevant to what you’re trying to achieve. Finding the “that’s enough” point is tricky though.

The problem is the API itself has to be language agnostic so either we need someone who understands the API fully that maintains these wrapper functions for each language similar to how binaries are created for each individual operating system from the OS agnostic source code or we need tutorials that explain how to use the API, and create one’s own wrappers from scratch, similar to compiling a program from it’s source code. It’s like having progressive levels of federation and literate dependency.

@drunkcod

If you do want to know what’s going on well then you’ll simply have to read up on all the constituent pieces and there’s really not feasible for anyone to create a “tutorial” that goes through all of them in enough detail to be both useful as a quick start and to educate about everything from json to http, mime types, asynchronous calls, some implementation language and doe something useful at the same time.

For the sake of creating an app a wrapper would do fine. For the sake of actually educating myself and others yes I do want to actually learn how this all works. The problem is identifying all the constituent pieces and the degree one needs to read up on them. I kind of wish the code examples were color coded or something so I knew which parts belonged to what. Also if you need to understand rest and http then how much do you need to know and what are you looking for? I mean you shouldn’t have to take an entire course just to make a hello world app. Hence the need for wrappers but there should be a clear path for MAKING those wrappers at the same time, or something else similar, because odds are someone will wan to get inventive.

[happybeing]

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 . 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)

[JBishop]

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

@Pierce

Scanning through the forum I see so many good ideas and extensive conversations. Little of which turn into formalized documentation. […] Will they ever be refined? If so when? I’m kinda worried that so many of these great ideas will get buried under more great ideas.

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

@happybeing

Someone could start by making a list (a to-do list?) of such instances with links to where each is discussed.

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:

@Blindsite2k

Speaking as one with rather limited code experience I’m finding this documentation to be rather confusing. So some small example applications or code snippets to go with the json to show how the examples would fit into an app would be good as well as annotations to explain in English what it all meant.

@happybeing

So I don’t think we’ll see much of this until someone with the time and ability learns to use the API and starts writing a coding tutorial as they go.

@Josh

I’d be happy to throw some money in a pot for a thorough tut. Community engagement program perhaps what can be more engaging than educating the community?

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?

[Blindsite2k]

@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?

[JBishop]

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.

[Blindsite2k]

@JBishop

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?

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.

@JBishop

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.

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.

[Blindsite2k]

Okay after reading this

drunkcod/Safenet/blob/master/Launcher API 0.5 Notes.md

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.

[Traktion]

@Blindsite2k

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

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.

[JBishop]

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)

[Blindsite2k]

@Traktion

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.

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.

[dirvine]

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.

[Blindsite2k]

@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.

[dirvine]

@Blindsite2k

Okay first question. What is “this”?

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.

[whiteoutmashups]

@Blindsite2k

I generally like to know whats going on under the hood

…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…

[drunkcod]

@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 Nanyang Technological University should be sufficient to give you enough information to understand how it ties together.

[Blindsite2k]

@whiteoutmashups

Mr. Irvine just gave you links to REST.

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

@whiteoutmashups

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

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.

@whiteoutmashups

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

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?