Skip to content

Commit de21137

Browse files
souenzzosouenzzo
committed
Better readme file, following aws-api design/steps
1 parent d52e164 commit de21137

File tree

3 files changed

+106
-59
lines changed

3 files changed

+106
-59
lines changed

‎README.md‎

Lines changed: 60 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -4,43 +4,83 @@ gcp-api is a Clojure library which provides programmatic access to GCP services
44

55
## Rationale
66

7-
See aws-api's rationale [here](https://github.com/cognitect-labs/aws-api#rationale).
7+
See aws-api's rationale [here](https://github.com/cognitect-labs/aws-api#rationale).
88

9+
## Approach
910

10-
## Approach
11+
Much the same as aws-api's [approach](https://github.com/cognitect-labs/aws-api#approach), this library publishes
12+
descriptor files that specify the operations, inputs, and outputs. These descriptor files are created from
13+
the [GCP discovery documents](https://developers.google.com/discovery/v1/reference).
1114

12-
Much the same as aws-api's [approach](https://github.com/cognitect-labs/aws-api#rationale), this library publishes descriptor files that specify the operations, inputs, and outputs.
13-
These descriptor files are created from the [GCP discovery documents](https://developers.google.com/discovery/v1/reference).
14-
15-
The generated descriptor files are published in a separate repository located [here](https://github.com/ComputeSoftware/gcp-api-descriptors).
15+
The generated descriptor files are published in a separate repository
16+
located [here](https://github.com/ComputeSoftware/gcp-api-descriptors).
1617

1718
## Usage
1819

19-
Using gcp-api requires you to add `gcp-api` and the service(s) of your choosing.
20-
In the below example we add the [GCP Compute Engine API](https://cloud.google.com/compute/docs/reference/rest/v1/) `gcp-api/compute`.
21-
Note that you must replace part of the `:deps/root` path with the API version you want to use.
20+
Using gcp-api requires you to add `gcp-api/gcp-api` and the service(s) of your choosing. In the below example we add
21+
the [GCP Compute Engine API](https://cloud.google.com/compute/docs/reference/rest/v1/) `gcp-api/compute`. Note that you
22+
must replace part of the `:deps/root` path with the API version you want to use.
23+
24+
To use, for example, the [compute v1 api](https://cloud.google.com/compute/docs/reference/rest/v1), add the following to
25+
`deps.edn`
2226

2327
```clojure
24-
gcp-api {:git/url "https://github.com/ComputeSoftware/gcp-api.git"
25-
:sha "<most recent sha>"}
26-
gcp-api/compute {:git/url "[email protected]:ComputeSoftware/gcp-api-descriptors.git"
27-
:sha "<most recent sha>"
28-
:deps/root "compute/<version>"}
28+
gcp-api/gcp-api {:git/url "https://github.com/ComputeSoftware/gcp-api.git"
29+
;; update this sha to the most recent
30+
:sha "d52e1646077a49fd0f5fadede7cc6e971a79127a"}
31+
gcp-api/compute {:git/url "https://github.com/ComputeSoftware/gcp-api-descriptors.git"
32+
;; update this sha to the most recent
33+
:sha "7b00d7c1ff31b03e9cd7df4189ae8dd8e533eec4"
34+
;; you can find other roots by browsing at directories in
35+
;; https://github.com/ComputeSoftware/gcp-api-descriptors
36+
:deps/root "compute/v1"}
2937
```
3038

31-
3239
```clojure
3340
(require '[compute.gcp.api :as gcp-api])
34-
35-
(def client
41+
;; Create a client:
42+
(def compute-v1
3643
(gcp-api/client {:api :compute
3744
:version "v1"}))
38-
45+
;; Ask what ops your client can perform
46+
;; It will return a descriptive map describing the supported parameters, response shape, and other info
47+
(gcp-api/ops compute-v1)
48+
=> {...
49+
"compute.instances.list" {:compute.gcp.descriptor/http-method :get
50+
:compute.gcp.descriptor/path "projects/{project}/zones/{zone}/instances"
51+
:compute.gcp.descriptor/response ...
52+
:compute.gcp.descriptor/parameters {"zone" {"type" "string"
53+
"description" "The name of the zone for this request."
54+
"required" true
55+
"pattern" "[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?"
56+
"location" "path"}
57+
"maxResults" {"type" "integer"
58+
"description" "The maximum number of results per page that should be returned. If the number of available results is larger than `maxResults`, Compute Engine returns a `nextPageToken` that can be used to get the next page of results in subsequent list requests. Acceptable values are `0` to `500`, inclusive. (Default: `500`)"
59+
"default" "500"
60+
"format" "uint32"
61+
"minimum" "0"
62+
"location" "query"}
63+
...}
64+
:compute.gcp.descriptor/description "Retrieves the list of instances contained within the specified zone."}
65+
...}
66+
67+
;; Look up docs for an operation:
68+
(gcp-api/doc compute-v1 "compute.instances.list")
69+
70+
71+
;; Do stuff:
3972
(gcp-api/invoke
40-
client
73+
compute-v1
4174
{:op "compute.instances.list"
4275
:request {:project "my-project"
4376
:zone "us-central1-c"}})
77+
=> {:kind "compute#instanceList"
78+
:id "projects/my-project/zones/us-central1-c/instances"
79+
:selfLink "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-c/instances"
80+
:items [{:description ""
81+
:name "example-01"
82+
...}]}
83+
4484
```
4585

4686
## Prior Art
@@ -51,5 +91,4 @@ gcp-api/compute {:git/url "[email protected]:ComputeSoftware/gcp-api-descriptors.
5191

5292
Copyright © 2020 Compute Software
5393

54-
Distributed under the Eclipse Public License either version 2.0 or (at
55-
your option) any later version.
94+
Distributed under the Eclipse Public License either version 2.0 or (at your option) any later version.

‎deps.edn‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,10 @@
1111
:test-runner {:extra-deps {lambdaisland/kaocha {:mvn/version "1.0.672"}}
1212
:main-opts ["-m" "kaocha.runner"]}
1313
:dev {:extra-paths ["resources" "env" "gcp-api-descriptors"]
14-
:extra-deps {com.climate/claypoole {:mvn/version "1.1.4"}}}
14+
:extra-deps {com.climate/claypoole {:mvn/version "1.1.4"}
15+
gcp-api/compute {:git/url "https://github.com/ComputeSoftware/gcp-api-descriptors.git"
16+
:sha "7b00d7c1ff31b03e9cd7df4189ae8dd8e533eec4"
17+
:deps/root "compute/v1"}}}
1518
:descriptors {:extra-deps {gcp-api/descriptors {:local/root "gcp-api-descriptors"}}}
1619
:jar {:extra-deps {seancorfield/depstar {:mvn/version "1.1.104"}}
1720
:main-opts ["-m" "hf.depstar.jar" "lib.jar"]}}}

‎src/compute/gcp/api.clj‎

Lines changed: 42 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
11
(ns compute.gcp.api
22
(:require
3-
[clojure.string :as str]
43
[clojure.core.async :as async]
5-
[compute.gcp.descriptor :as descriptors]
6-
[compute.gcp.impl.client :as client-impl]
7-
[compute.gcp.credentials :as creds]
8-
[compute.gcp.retry :as retry]
4+
[clojure.string :as str]
95
[compute.gcp.async.api :as async.api]
10-
[compute.gcp.descriptor :as descriptor]))
6+
[compute.gcp.credentials :as creds]
7+
[compute.gcp.descriptor :as descriptor]
8+
[compute.gcp.impl.client :as client-impl]
9+
[compute.gcp.retry :as retry]))
1110

1211
(def ^:private *default-http-client
1312
(delay
@@ -19,7 +18,7 @@
1918

2019
(defn client
2120
[{:keys [api version http-client credentials-provider backoff retriable?]}]
22-
(let [descriptor (descriptors/load-descriptor api version)
21+
(let [descriptor (descriptor/load-descriptor api version)
2322
credentials-provider (or credentials-provider (creds/get-default))]
2423
(client-impl/->Client
2524
{::http-client (or http-client (default-http-client))
@@ -31,45 +30,51 @@
3130

3231
;; TODO
3332
(defn doc-str
34-
[{:keys [documentation request required response refs] :as doc}]
35-
(when doc
36-
(str/join "\n"
37-
(cond-> ["-------------------------"
38-
(:name doc)
39-
""
40-
documentation]
41-
request
42-
(into [""
43-
"-------------------------"
44-
"Request"
45-
""
46-
(with-out-str (clojure.pprint/pprint request))])
47-
required
48-
(into ["Required"
49-
""
50-
(with-out-str (clojure.pprint/pprint required))])
51-
response
52-
(into ["-------------------------"
53-
"Response"
54-
""
55-
(with-out-str (clojure.pprint/pprint response))])
56-
refs
57-
(into ["-------------------------"
58-
"Given"
59-
""
60-
(with-out-str (clojure.pprint/pprint refs))])))))
33+
[{::descriptor/keys [operation description parameters response] :as doc}]
34+
(let [required (keep (fn [[parameter {:strs [required]}]]
35+
(when required
36+
(keyword parameter)))
37+
parameters)]
38+
(when doc
39+
(str/join "\n"
40+
(cond-> ["-------------------------"
41+
operation
42+
""
43+
description]
44+
parameters
45+
(into [""
46+
"-------------------------"
47+
"Request"
48+
""
49+
(with-out-str (clojure.pprint/pprint parameters))])
50+
required
51+
(into ["Required"
52+
""
53+
(with-out-str (clojure.pprint/pprint required))])
54+
response
55+
(into ["-------------------------"
56+
"Response"
57+
""
58+
(with-out-str (clojure.pprint/pprint response))]))))))
6159

6260

6361
(defn doc-data
6462
[client op]
6563
(let [op-descriptor (descriptor/get-op-info (::api-descriptor client) op)]
6664
(-> op-descriptor
67-
(select-keys [:description :parameters :responses]))))
68-
65+
(select-keys [:description :parameters :responses]))))
6966

7067
(defn ops
7168
[client]
72-
(keys (get-in client [::api-descriptor ::descriptor/op->info])))
69+
(::descriptor/op->info (::api-descriptor (client-impl/-get-info client))))
70+
71+
(defn doc
72+
[client operation]
73+
(println (or (some-> client ops
74+
(get operation)
75+
(assoc :compute.gcp.descriptor/operation operation)
76+
doc-str)
77+
(str "No docs for " (name operation)))))
7378

7479

7580
(defn invoke

0 commit comments

Comments
 (0)