bc35467 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

Merge branch '2018-era-draft' of https://github.com/urbit/docs into 2018-era-draft

bc35467Robert8 years ago

docs/tutorials/gall/api.udon+3−7

compare with master

unifiedsplit

@@ -7,6 +7,8 @@

8# API Connectors

10+> Note: This lesson depends on some code that needs to be updated before the examples will work correctly. This will be addressed in the near future. We apologize!

11+

10Most people have lots of data stored in online services, many of

12Most people have lots of data stored in online services, many of

11which have APIs. API connectors allow the user to access this

13which have APIs. API connectors allow the user to access this

12data from within their Urbit.

14data from within their Urbit.

@@ -86,13 +88,7 @@ for a particular piece of data, while `%y` is a request for a

86directory listing. Roughly, `%x` means Unix `cat` and `%y` means

88directory listing. Roughly, `%x` means Unix `cat` and `%y` means

87Unix `ls`.

89Unix `ls`.

89−> Sometimes you wish to expose a tree where a part of the path

91+> Sometimes you wish to expose a tree where a part of the path can't be enumerated. For example, a `%y` of `/issues/by-repo` "should" produce a list of all Github users, but we don't do that because it's too long. Instead, we just produce our own username (from the `web.plan` file). You can still access repos from other users, you just don't see them in the directory listing.

90−> can't be enumerated. For example, a `%y` of `/issues/by-repo`

91−> "should" produce a list of all Github users, but we don't do

92−> that because it's too long. Instead, we just produce our own

93−> username (from the `web.plan` file). You can still access

94−> repos from other users, you just don't see them in the

95−> directory listing.

97The usual flow for implementing this tree of data makes heavy use

93The usual flow for implementing this tree of data makes heavy use

98of the `connector` library. This library is well documented in

94of the `connector` library. This library is well documented in

docs/tutorials/gall/http.udon+11−11

@@ -24,7 +24,7 @@ code isn't 2xx. Save the following as `app/up.hoon`:

24|%

25+$ move [bone card]

26+$ card

27− $% [%hiss wire unit-iden=$~ mark=%httr cage=[mark=%purl vase=purl]]

27+ $% [%hiss wire unit-iden=$~ mark=%httr cage=[mark=%purl vase=purl:eyre]]

28 [%wait wire @da]

29 ==

30+$ action

@@ -35,7 +35,7 @@ code isn't 2xx. Save the following as `app/up.hoon`:

35--

36|_ [hid=bowl:gall on=_| in-progress=_| target=@t]

37++ poke-atom

38− |= url-or-command=@t ^- (quip move +>)

38+ |= url-or-command=@t ^- (quip move _+>)

39 =+ ^- act/action

40 ?: ?=($on url-or-command) [%on ~]

41 ?: ?=($off url-or-command) [%off ~]

@@ -45,11 +45,11 @@ code isn't 2xx. Save the following as `app/up.hoon`:

45 $off [~ +>.$(on |)]

46 $on

47 :- ?: |(on in-progress) ~

48− [ost.hid %hiss /request ~ %httr %purl (need (epur target))]~

48+ [ost.hid %hiss /request ~ %httr %purl (need (de-purl:html target))]~

49 +>.$(on &, in-progress &)

50 ==

51++ sigh-httr

52− |= [wir=wire code=@ud headers=mess body=(unit octs)]

52+ |= [wir=wire code=@ud headers=mess:eyre body=(unit octs)]

53 ~& 'arrive here'

54 ^- [(list move) _+>.$]

55 ?: &((gte code 200) (lth code 300))

@@ -62,10 +62,10 @@ code isn't 2xx. Save the following as `app/up.hoon`:

62 :_ +>.$

63 [ost.hid %wait /timer (add ~s10 now.hid)]~

64++ wake-timer

65− |= [wir=wire $~] ^- (quip move +>)

65+ |= [wir=wire $~] ^- (quip move _+>)

66 ?: on

67 :_ +>.$

68− [ost.hid %hiss /request ~ %httr %purl (need (epur target))]~

68+ [ost.hid %hiss /request ~ %httr %purl (need (de-purl:html target))]~

69 [~ +>.$(in-progress |)]

70::

71++ prep ~& target _`. :: computed when the source file changes;

@@ -88,9 +88,9 @@ r=cage]` from `zuse`.

89> Recall that `++unit` means "maybe". Formally, "`(unit a)` is either null or a pair of null and a value in `a`". Also recall that to pull a value out of a unit (`u.unit`), you must first verify that the unit is not null (for example with `?~`). See `++need`.

91−A `purl` is a parsed url structure, which can be created with `++epur`,

91+A `purl:eyre` is a parsed url structure, which can be created with `de-purl:html`,

92which is a function that takes a url as text and parses it into a `(unit

93−purl)`. Thus, the result is null if and only if the url is malformed.

93+purl:eyre)`. Thus, the result is null if and only if the url is malformed.

94'Purl' is also the mark which will be applied to this result.

96When you send this request, you can expect a `%sigh` with the

@@ -104,7 +104,7 @@ produce a `%wake` when the time comes.

104Let's take a look at our state:

105

106```

107−|_ [hid=bowl:gall on=_| in-progress=_| target=@t}

107+|_ [hid=bowl:gall on=_| in-progress=_| target=@t]

108```

109

110We have three pieces of app-specific state. `target` is the url

@@ -137,7 +137,7 @@ actual url, so we save it in `target`.

137Here's the move that sends the HTTP request:

138

139```

140−[ost.hid %hiss /request ~ %httr %purl (need (epur target))]

140+[ost.hid %hiss /request ~ %httr %purl (need (de-purl:html target))]

141```

142

143> Remember, we are expected to produce a *list* of moves. Note the `~` after the move in the full example. This is a convenient shortcut for creating a list of a single element. It's part of a small family of such shortcuts. `~[a b c]` is `[a b c ~]`, `[a b c]~` is `[[a b c] ~]` and `\`[a b c]` is `[~ a b c]`. These may be mixed and matched to create various convoluted structures and emojis.

@@ -151,7 +151,7 @@ visualize on one line. Here it is more pedantically:

151 wire=/request

152 unit-iden=~

153 mark=%httr

154− cage=[%purl (need (epur target))]

154+ cage=[%purl (need (de-purl:html target))]

155==

156```

157

docs/tutorials/gall/security-driver.udon+13−3

@@ -33,14 +33,24 @@ cases you'll need to make very few changes to one of these

33models.

35Still, it's worth seeing one or two built from the ground up.

36−Here, we'll build a connector for the Github API v3. The

36+Here, we'll build a connector for the Github API v3. (It's already in `/sec/com/github.hoon` if you want to see it.)

37+

38+The

37simplest way to interact with the Github API is to just fetch

39simplest way to interact with the Github API is to just fetch

38−https://api.github.com from the dojo:

40+https://api.github.com from the dojo. First, run this:

41+

42+```

43+> |init-auth-basic /com/github

44+```

45+

46+Input your Github username and password as directed. Next:

40```

48```

41~your-urbit:dojo> +https://api.github.com

49~your-urbit:dojo> +https://api.github.com

42```

50```

52+> Note: the current version of this API is outdated, so you'll get a 403 message at this point. We need to update this so you can follow along with the examples. We're sorry!

53+

44Github exposes a few endpoints to the general web, and the root

54Github exposes a few endpoints to the general web, and the root

45endpoint is one of them. This gives you a textual representation

55endpoint is one of them. This gives you a textual representation

46of a JSON object that contains a bunch of urls to other parts of

56of a JSON object that contains a bunch of urls to other parts of

@@ -91,7 +101,7 @@ you're logged in as.

91You can similarly POST:

101You can similarly POST:

102

93```

103```

94−~your-urbit:dojo> +https://api.github.com/gists &json _(cork poja need) '{"files":{"file1.txt":{"content":"can\'t stop the signal"}}}'

104+~your-urbit:dojo> +https://api.github.com/gists &json _(cork de-json:html need) '{"files":{"file1.txt":{"content":"can\'t stop the signal"}}}'

95```

105```

106

97This creates a gist, go to `https://gist.github.com/<username>` to

107This creates a gist, go to `https://gist.github.com/<username>` to