Help making tutorial apps

[Blindsite2k]

Okay I want to make very simple tutorial applications, mostly for web developers and such that demonstrate how to utilize the SAFE network APIs (and for my own reference purposes given I am a web developer and designer). However I’m struggling to understand the api tutorials on the maidsafe readme site given a couple of things. 1. Examples are presented using different languages. Some are offered in json, others in nodejs. While it’s awesome to see they are compatible with multiple languages and indeed it’s reasonable that they’re all javascript derived nodejs isn’t the same as json nor is it the same as javascript. And when coding one wants to be precise. 2. There aren’t a lot of different examples for each api. Or examples of them in action.

Like one of the basic apps i want to create is a simple “Hello World” type app that simply requests the user’s public Id from the launcher and disppays it as text message “Hello “Public ID”!” Or something like that. Or add a file from the user’s SAFE drive. Like say if the user has pics on their safedrive, display one randomly or have them display in sequence below the greeting. How does one create a prompt or web interface to upload to one’s SAFE drive? I’m not trying to build a massive app here I just want to create little demo examples for each core function for future reference and have them clearly documented so anyone can learn from them and utilize them.

[drunkcod]

Could you elaborate on the “mixed languages” point?
From what I can see all the usage examples are nodejs and the json bits are the payloads and return values.

Which is very much to be expected since the Launcher API is a http based (although not “RESTful”) api accepting json payloads, which makes it very easy to access from any language.

(one niggle is that it’s not consistent in always returning json though (I’m looking at you OK/Unautorized/Field missing responses…)

For your example app what you want is /auth (/auth)
and quite likely /dns (/dns)

AFAIK “public id” from the Launcher API perspective is simply your first registered long name (you can have as many as you’d like)

To display the users pictures you most likely want to ask for the “SAFE_DRIVE_ACCESS” permission when authing and then go spelunking through the users file using the /nfs (/nfs/directory/:rootPath/:directoryPath/) endpoint with the ‘drive’ root. (leave path empty for the root directory).

[mvanzyl]

I think the intent is to have live codepen type areas or examples of the API actually in use to show how to apply them to a site, apps, etc. I do some front end stuff, but having a screenshot of a node example for the API doesn’t really show me step by step how to use it to display a photo from SAFE or request launcher access or whatever. Having the process in context with additional details and such would be spectacularly helpful for a lot of us more casual users…

[Blindsite2k]

@drunkcod

Could you elaborate on the “mixed languages” point? From what I can see all the usage examples are nodejs and the json bits are the payloads and return values.

Yeah I could have sworn there were json examples but in any event there still the matter o how does one utilize the example in a language other than nodejs. I mean it isn’t a big leap from say node.js to say javascript or json but there are some differences. Nevermind other languages.

@drunkcod

For your example app what you want is /auth (https://maidsafe.readme.io/docs/auth)and quite likely /dns (https://maidsafe.readme.io/docs/dns-list-long-names)

AFAIK “public id” from the Launcher API perspective is simply your first registered long name (you can have as many as you’d like)

Awesome, I’ll give those another read over. How do you manage other long names?

@drunkcod

To display the users pictures you most likely want to ask for the “SAFE_DRIVE_ACCESS” permission when authing and then go spelunking through the users file using the /nfs (https://maidsafe.readme.io/docs/nfs-get-directory) endpoint with the ‘drive’ root. (leave path empty for the root directory).

Lol yet more stuff to read over but how do you scan through the files is what I’m wondering.

[Blindsite2k]

Is the Request payload a seperate file or just a seperate segment of script? How would you write out the example in javascript insead of node.js for example? Or in json? Basically what I’m wondering is: How much of that example is node.js vs how much of it is the API. How does the API look in different languages. Javascript based languages are good for this because they are so similar but having other language examples would also be good because it would show in even starker relief where the API stood out and how to apply it.

Also note the code examples on the readme.io site are not annotated.

[hintofbasil]

Having written 70% of a Python wrapper around the API. The code examples are actually very representative of how to use the API in other languages. Having no knowledge of NodeJS I was able to understand the API quite happily from them.

From your first post you seem to be a little confused in terminology. NodeJS and JSON are not programming languages. The examples are all written in Javascript. NodeJS is a javascript runtime and framework (you could argue that makes it a language but it would be more like javascript version 2). JSON is simply a data format. People tend to treat NodeJS as a separate language because it changes javascript so much but it’s technically still javascript.

All languages communicating with the API are required to use JSON however they are not required to use javascript or NodeJS.

A simple example of using the API in python with requests is

response = requests.get('http://localhost:8100/auth',
    headers = json.dumps(
        {
            'Authorization': 'Bearer <TOKEN>'
        }
    )
if response.status_code == 200:
    # token is valid
else:
    # token is not valid

You can see the use of json in the lines headers = json.dumps({...}). The rest of the code simply POSTs the data to the launcher (localhost:8100). This is exactly what the offical documentation shows however they use NodeJS to do the POSTing.

[Blindsite2k]

Okay I’m sorry but you have made little to no sense here. If it’s all javascript why not label it as such? JSON is merely a data format? From what I’ve studied so far you can write json like 2 or 3 different ways. I don’t care what you call it so long as it’s clear as to how to write the syntax. Do I write it this way or that way. Took me a minute of studying the python snippet you posted to spot the API segments. So basically you store the payload containing the app information in a json database.then create if else statements to handle errors and to check if the app has been authorized or not. Though I’md still confused about where the authorizeation token is defined. Also it’s written differently in both examples.

headers = json.dumps(
    {
        'Authorization': 'Bearer <TOKEN>'
    }

if (response.statusCode === 401) {
return console.error(‘Failed to authorise’);
}
console.log(‘Auth token’, body.token);
};

[hintofbasil]

@Blindsite2k

If it’s all javascript why not label it as such?

It simply makes more sense to a developer to call it NodeJS instead of javascript. It gives more information. It’s similar to saying “I am from Troon” instead of “I am from Scotland” - it gives more specific information while also implying the latter.

@Blindsite2k

From what I’ve studied so far you can write json like 2 or 3 different ways.

I guess my example is a little confusing in this regard. JSON is always a string with a very specific format. This format is {"key": "value", "key2": "value2"}. This is typically called a dictionary as it works very similarly to a real world dictionary. If you look up "key" you find "value", if you look up "key2" you find "value2". White space in json is ignored so {"key":"value"} is exactly the same as

{
    "key": "value"
}

The API specification states certain keys and values must be sent to each endpoint. In this example the key "Authorization" is required. When the API looks up the "Authorization" key a value "Bearer <TOKEN>" is expected to be found. Other API end points may expect other keys and associated values.

In my code I have used a function json.dumps(…) which generates the json string for us. In this circumstance it would return the string {"Authorization": "Bearer <TOKEN>"}. This means my code can be re-written as

response = requests.get('http://localhost:8100/auth',
    headers = '{"Authorization": "Bearer <TOKEN>"}'
    )
if response.status_code == 200:
    # token is valid
else:
    # token is not valid

JSON is simply a string (text) which is formatted in a specific way.

@Blindsite2k

So basically you store the payload containing the app information in a json database.

All HTTP information is simply human-readable text being sent backwards and forwards. We simply send out a human readable JSON string to the API and save the response to look it. I personally called the response “response” in this example.

@Blindsite2k

then create if else statements to handle errors and to check if the app has been authorized or not.

Exactly!

@Blindsite2k

Though I’md still confused about where the authorizeation token is defined.

This token is returned from a different API call POST /auth. As you can see from the documentation for POST /auth it returns the following JSON string:

{
  "token": "<TOKEN>",
  "permissions": Array[String]
}

From this we extract our token by looking up the "token" key. We can then we use this token in other API calls such as our example call.

Our example call GET /auth actually checks whether our token is valid. If we give it a valid token (our app is authorized) we get a status_code of 200. If we give it an invalid token (our app is not authorized) we get a status_code of 401.
These status codes are all pre-defined in the HTTP protocol. The API only uses 3-4 of them.

Hope this makes a little more sense.

[Blindsite2k]

@hintofbasil

This token is returned from a different API call POST /auth. As you can see from the documentation for POST /auth it returns the following JSON string:

{
“token”: “<TOKEN>”,
“permissions”: Array[String]
}

Yes Mr. Trainman round and round Neo runs through the infinite mobius strip subway loop. Token is defined by the json which defines it as token. Sorry I must be missing something here. Seriously I’m not understanding the examples page on readme.io. They’re all broken up and don’t make sense. And there seem to be loops in logic. Could you please clarify?

[hdastwb]

The table at the bottom of the response section gives a more detailed explanation of the fields in the response payload. For instance, this is what it says about the token:

JWT token that has to be used in all the authorised API calls. This token has to be passed in the Authorization header field for making authorised API calls.

[Blindsite2k]

" JWT token that has to be used in all the authorised API calls. This token has to be passed in the Authorization header field for making authorised API calls."

This is not a code example and it doesn’t make sense as plain English. What does this MEAN?! JWT = what? Okay so the token needs to be used in all authorized api calls and is passed in the header field to make those calls. That still doesn’t define what the token is as far as code goes. Is it the word “token”, is it an cryptographic string, is it an integer, is it the Scottish anthem? What is it? var token = ??? We know what the token is used for, we know that the token is required but this does not explain what the token IS or where it comes from.

[hdastwb]

Well, since it’s in the response payload for the /auth request you can receive a token by making an /auth request with the correct parameters for your app (as documented in the request portion of that page) and then reading it out of the server’s response. After you have a token you can just pass it as-is to other requests, which suggests that it’s some sort of string. This is essentially all that you need to know about it in order to use it correctly, but it doesn’t say much as to what it actually is because that is beyond the scope of the documentation since it has an associated standard:

JWT.IO - JSON Web Tokens Introduction

You can also verify that this is the correct form for the tokens by building a small test app which just makes an /auth request and prints the token it gets to the console, or by using a program like Wireshark to look at packets going over your loopback interface and track the connection between the demo app and the launcher.

[Blindsite2k]

Can someone please translate what I’m saying into developer? I think we’re having a communication breakdown here.

@hdastwb

Well, since it’s in the response payload for the /auth request you can receive a token by making an /auth request with the correct parameters for your app (as documented in the request portion of that page) and then reading it out of the server’s response.

So it’s a string or something passed to the json payload database from the maidsafe api? Like I’m looking through the example code, all of it and no where arr ‘Auth token’ and body.token defined

console.log(‘Auth token’, body.token);

It looks like it’s saying print “Auth token” + body.token but what is body.token? It was never defined in the code. Forget the English definition, if its not in code it doesn’t exist for the program! Where is it defined? It’s like math, you have to declare and define all your variables.

@hdastwb

You can also verify that this is the correct form for the tokens by building a small test app which just makes an /auth request and prints the token it gets to the console, or by using a program like Wireshark to look at packets going over your loopback interface and track the connection between the demo app and the launcher.

Wireshark to examine packets? Dude I have no doubt this code is correct but I can’t write a program if I can’t understand what all of this does or how the logic flow works. Every element needs to clearly defined both in code and English and shown as to what it does, where it’s coming from and where it’s going. There’s a big difference between knowing the code and teaching the code.

[drunkcod]

@Blindsite2k from client perspective the tokens could be variants of the Scottish anthem or anything else.
Client shouldn’t care but simply treat it as an opaque blob to be passed back.

So from that perspective the token, is just a token. Represented as a string. You pass it in to identify yourself and that’s it. The question then is how do you get one and that’s where the authorization endpoint /auth comes in.

So what the token is is simply an identifier for who you are (or what app is accessing the API).
Where it comes from: You get it from the API by requesting access, if granted you get a token in response.

Simply gluing together the POST and GET examples for the token very quickly gives you something that can be run against the Launcher API to both authenticate and verify the you can make authenticated calls.

“body.token” comes from the response from the api, body is defined as a parameter to onResponse that it has a “token” field is due to the endpoint returning json, that gets parsed into the object automatically.
This is what the “response” section means, it defines the structure of the json reply.

I think it would maybe be helpful for us trying to help you if you could elaborate a bit about your own prior experience since we seem to have a hard time answering “at the right level”.

[Blindsite2k]

My experience is with HTML, javascript and CSS. I’ve played around with python, c++ and a very wee bit with java but can’t really code anything legible in either of them. (I think I speak better Japanese than I do Python or Java and I’ve learned most of that from anime.) I’ve looked into JSON and am quite intrigued by it but am still struggling with how to correctly format it and how to pass data in and out of the databases. (Hence why I’m bitching so much about correct syntax and formatting.) I’m interested in nodejs but don’t really know how to write it. Consider javascript my shallow end of the pool, JSON is the middle line and nodejs is the deep end. Consider application languages like python, c++ and java to be way out there in the ocean.

[hdastwb]

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.

[Blindsite2k]

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.

[Blindsite2k]

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.

[dirvine]

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.

[Blindsite2k]

@dirvine

So it may be that a good idea is to uncover that first? an you take a look at this http://rest.elkstein.org/

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?