3d454fe · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

minor copyediting

3d454feGalen Wolfe-Pauly11 years ago

docs/programming/arvo/system/api.md+7−7

compare with master

unifiedsplit

@@ -23,7 +23,7 @@ app accomplishes both for Github.

23After starting `%gh` (`|start %gh`), let's look at the root of

24the tree that `%gh` exposes:

26− ~sampel-sipnym:dojo> .^(arch %gy /=gh=)

26+ ~your-urbit:dojo> .^(arch %gy /=gh=)

27 [fil=~ dir={[p=~.issues q=~]}]

29`%gh` is currently a skeleton -- it contains examples of all the

@@ -31,7 +31,7 @@ functionality necessary for a connector, but many endpoints

31aren't implemented. As we can see here, only issues are

32implemented. We can explore this tree:

34− ~sampel-sipnym:dojo> .^(arch %gy /=gh=/issues)

34+ ~your-urbit:dojo> .^(arch %gy /=gh=/issues)

35 [fil=~ dir={[p=~.by-repo q=~] [p=~.mine q=~]}]

37And eventually:

@@ -49,9 +49,9 @@ the `:pipe` app:

49 :pipe|connect %gh /listen/philipcmonktest/testing/issues/'issue_comment' %public

51Now creating an issue results in the following message in your

52−`%public` channel:

52+`%public` `:talk` channel:

54− ~sampel-sipnym[philipcmonktest@github]: opened issue #11: i found a bug!

54+ ~your-urbit[philipcmonktest@github]: opened issue #11: i found a bug!

56You'll also get notifications of issue status changes and

57comments.

@@ -78,7 +78,7 @@ Unix `ls`.

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

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

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

81−> repos from other uesrs, you just don't see them in the

81+> repos from other users, you just don't see them in the

82> directory listing.

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

@@ -100,7 +100,7 @@ list of all the places we can request. A place consists of:

100 to match `/issues/<user>/<repo>` use `{$issues @t @t $~}`.

101

102- `read-x`, called when someone tries to read the place with

103− care `%x`. Should produce a single move, usually either a

103+ `care` `%x`. Should produce a single move, usually either a

104 `%diff` response if we can immediately answer or a `%hiss`

105 http request if we need to make a request to the api. See the

106 `++read-*` functions in `++helpers` for some common handlers.

@@ -175,7 +175,7 @@ up-to-date.

175Flow of control starts in `++peer-listen`, where we just call

176`++listen`. In `++listen`, for each event in the list of events,

177we check to see if we have that hook set up (by checking whether

178−it exists in `hook`). If so, we call `++update-hook` to add th

178+it exists in `hook`). If so, we call `++update-hook` to add the

179current bone to the set of listeners. Otherwise, we call

180`++create-hook`, which sends a request to Github to set up the

181new webhook. We also create an entry in `hook` with the current

docs/programming/arvo/system/security-driver.md+14−13

@@ -29,15 +29,15 @@ models.

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

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

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

32−https://api.github.com.

32+https://api.github.com from the dojo:

34− +https://api.github.com

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

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

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

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

39Github's API. This is exactly the same response you would get

40−from just running `curl` on UNIX.

40+from just running `curl https://api.github.com` on UNIX.

42If we don't have a security driver for Github yet, many of the

43endpoints won't be accessible, or they will only have publicly

@@ -70,7 +70,7 @@ To try this out, we first have to initialize our credentials with

70`|init-auth-basic`, which prompts for the url of the service

71(api.github.com), username, and password. It stores this

72information in a manner that `%eyre` knows how to decode and send

73−put into your bale. Note that `|init-auth-basic` is standard for

73+put into your `bale`. Note that `|init-auth-basic` is standard for

74basic auth, but other auth schemes (like OAuth) are initialized

75in other ways.

@@ -80,8 +80,7 @@ you're logged in as.

81You can similarly POST:

83− +https://api.github.com/gists &json _(cork poja need)

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

84− '{"files":{"file1.txt":{"content":"can\'t stop the signal"}}}'

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

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

87see it.

86see it.

@@ -93,22 +92,24 @@ can send data of any mark as long as it has a conversion path to

93`%mime`.

92`%mime`.

95Let's take a look at the code and see if we can figure out what's

94Let's take a look at the code and see if we can figure out what's

96−happening here.

95+happening here:

96+

97+ /+ basic-auth

98First, we load a library called `basic-auth`. This library

99First, we load a library called `basic-auth`. This library

99exposes two items. `keys` is the type of the basic auth key,

100exposes two items. `keys` is the type of the basic auth key,

100which is essentially a base64'd username and password.

101which is essentially a base64'd username and password.

101−`standard` accepts a bale and produces a core with everything

102+`standard` accepts a `bale` and produces a core with everything

102we'll need to implement basic auth.

103we'll need to implement basic auth.

103

104

104Every security driver needs some amount of state, which is stored

105Every security driver needs some amount of state, which is stored

105−in the bale. The bale contains:

106+in `bale`. `bale` contains:

106

107

107- `our`, our urbit name

108- `our`, our urbit name

108- `now`, the current time

109- `now`, the current time

109- `eny`, 256 bits of entropy

110- `eny`, 256 bits of entropy

110−- `byk`, the urbit, desk, and case which the security driver is

111+- `byk`, the urbit, desk and case which the security driver is

111− running off

112+ running from

112- `usr`, the particular identity we're logging in with

113- `usr`, the particular identity we're logging in with

113- `dom`, the site we're accessing

114- `dom`, the site we're accessing

114- `key`, the secrets required to authenticate requests. The type

115- `key`, the secrets required to authenticate requests. The type

@@ -130,7 +131,7 @@ one of:

130 asking the user to visit the given url to continue the

131 asking the user to visit the given url to continue the

131 authentication process.

132 authentication process.

132

133

133−Every request to a Github url will be filtered through

134+Every request to a GitHub url will be filtered through

134`++filter-request`, and we want to add the authentication header

135`++filter-request`, and we want to add the authentication header

135to it. Our `++aut` core contains a function

136to it. Our `++aut` core contains a function

136`++out-addding-header`, which does exactly what we want.

137`++out-addding-header`, which does exactly what we want.

@@ -141,7 +142,7 @@ service url, username, and password, and it stores them next to

141the driver. In our case, that's

142the driver. In our case, that's

142`/=home=/sec/com/gitub/api/atom`. These keys are stored

143`/=home=/sec/com/gitub/api/atom`. These keys are stored

143encrypted, and you don't want to edit them directly. `%eyre`

144encrypted, and you don't want to edit them directly. `%eyre`

144−loads them directly into your bale.

145+loads them directly into your `bale`.

145

146

146# OAuth2

147# OAuth2

147

148