Help making tutorial apps

This discussion is also about providing helpful documentation to newcomers, so we should also be figuring out what the correct level to present this information to new developers is in general. For instance, the API documentation seems to assume a working knowledge of HTTP, JSON, and callback-based HTTP libraries like the one in Node.js. That’s good enough for those of us who’ve read the standards and who have been banging code against webservers for years, but in the tutorial app we should also include a brief overview of those things to get people who might not be as familiar with them up to speed first. Especially HTTP, since that’s crucial to understanding how the interface operates and since people don’t usually seem to have as much direct exposure to it.

4 Likes

Yeah like I know how to write html half decently, I can write css if I have a reference handy and I can UNDERSTAND javascript well enough to code it. But I haven’t memorized javascript and I am still learning the deeper stuff like JSON and I don’t really know anything about node.js. And there are those who are completely code illiterate. I’m probably going to learn a lot more javascript in the future what with SAFE coming out but I’m not by no means an expert yet. And I know pretty much nothing about HTTP protocols.

I feel rather embarrassed admitting how ignorant I am but hey I need to learn more and it seems like one of he crucial steps.

On W3schools for every lesson there’s a section that suggests what prerequsite knowledge you need to learn and where to learn it. So if you want to learn css a prereq is HTML, same with javascript. For these APIs there should also be stated prereqs and if the knowledge isn’t provided directly on the site it should be linked to somewhere so the prospective learner can go, study the code, upgrade their skills, come back and then understand the API more clearly.

I think the issue here is not programming languages per se’ but use of a particular pattern REST So it may be that a good idea is to uncover that first? an you take a look at this http://rest.elkstein.org/ @Blindsite2k and then let us know if it helps or hinders?

I suspect it may be that presenting REST Api which is a mechanism for transferring data/actions/responses between objects (networks/machines/other programs etc.), is the issue. Anyway I hope this helps, if it does we cna look at including something like this as an intro.

6 Likes

Just after having a quick look at this I’d say this opens up more questions than it answers. I’m not saying I couldn’t learn this but it’s “more complicated” rather than simplifying things if you get my meaning. It helps in that it may explain how things works, eventually, after perhaps a few weeks or a month of study about ReST, HTTP and how the network is formed. It hinders in that it doesn’t quickly explain what things do or how they do them so that one can get down to coding their app.

This is a quick example except from the page.

“REST is an architecture style for designing networked
applications. The idea is that, rather than using complex mechanisms
such as CORBA, RPC or SOAP to connect between machines, simple HTTP is
used to make calls between machines.”

What is CoRBA? What is RPC or SOAP? How do they all differ? How are they different from HTTP? This Rest tutorial is written for those who are familiar with these network protocols. So I’m kind of the wrong audience for this tutorial.

Let’s remember my original goal for this tutorial was to build a simple “Hello World” type app that perhaps displayed a random pic found in the user’s SAFE Drive. And I’m passionate enough about learning code and teaching code to others to actually bother having this discussion and try to learn all this. But some random guy who is just maybe curious and reading through the website might get intimidaed and just give up without trying. That’s WHY I’m doing all this work and I started this thread. To do some of the heavy lifting and take it from A to B somewhat. I’m used to helping noobs out and if I CAN’T understand it how can someone who has less coding ability than me who wants to learn understand it so they’ll be encouraged to learn more?

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.

2 Likes

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.

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

2 Likes

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.

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.

3 Likes

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.

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.

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

@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

@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

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

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.

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.

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

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)

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.

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