This is the github-api-cl Reference Manual, version 0.3.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Fri Sep 15 05:14:38 2023 GMT+0.
The main system appears first, followed by any subsystem dependency.
github-api-clThe lite Github rest v3 api client SDK
ccQpein
ccQpein
(GIT git@github.com:ccqpein/Github-API-CL.git)
Apache
# README #
This repo is the lite Github rest v3 api client.
Because I cannot find the whole Github rest api in one file, just several documents pages. So you might need to add api details by yourself into json file. api.json is the example.
Documents link is [here](https://developer.github.com/v3/)
## Usage ##
You can check ‘./example‘
### Dependencies ###
I use [yason](https://github.com/phmarek/yason) for json parser, [dexador](https://github.com/fukamachi/dexador) for http client.
### Install ###
This repo haven’t deploy to quicklisp yet, but you can git clone to ‘quicklisp/local-projects‘ folder and ‘(ql:quickload "github-api-cl")‘
### Read api.json file ###
Suppose we have ‘api.json‘ looks like:
“‘ json
{
"repositories": {
"repositories": {
"List repositories for a user": {
"parameters": [
["type", "string"],
["sort","string"],
["direction","string"]
],
"api": "GET /users/:username/repos",
"link": "https://developer.github.com/v3/repos/#list-repositories-for-a-user"
}
}
}
}
“‘
**Examples:**
“‘lisp
;; load system first
(ql:quickload "github-api-cl")
;; read api.json in this repo, path var is github-api-doc::*api-json-file-path*
(github-api-doc:read-api-json) ;; => return a hashtable of this json
;; OR you can give path specially
(github-api-doc:read-api-json #P"/path/to/api.json")
“‘
### Generate api instance ###
After read api.json file, you can generate api instance by using ‘github-api-doc:make-api-doc-from-json‘
**Examples:**
“‘ lisp
;; read api.json
(defparameter *api-docs* (github-api-doc:read-api-json))
;; &rest arguments are the steps of reading json
(defparameter *api-doc* (github-api-doc:make-api-doc-from-json *api-docs* "repositories" "repositories" "List repositories for a user"))
;; Get api-doc:
;;api-doc object:
;; api: GET /users/:username/repos,
;; http method: GET,
;; slots: (:username),
;; fmt-control: (/users/~a/repos)
;; parameters: ((type string) (sort string) (direction string))
;; OR, you can make instance manually
(setf *api-doc* (make-instance ’api-doc
:api "GET /users/:username/repos"
:parameters ’(("type" "string")
("sort" "string")
("direction" "string")))
“‘
‘api.json‘ is pretty flexible because it just a json file. So you don’t have to follow Github api structure if you don’t want to. Only part of api.json does ‘github-api-cl‘ care about is this part:
“‘json
{
"parameters": [
["type", "string"],
["sort","string"],
["direction","string"]
],
"api": "GET /users/:username/repos",
}
“‘
You can read this json file and ‘(github-api-doc:make-api-doc-from-json (github-api-doc:read-api-json #P"this-simple-api.json"))‘
### Make github-api client ###
Making github-api client:
“‘lisp
;; make instance of api-client
(defparameter *client-without-token* (make-instance ’github-client:api-client))
;; if you have token for github rest api call, make like this
(defparameter *client-with-token* (make-instance ’github-client:api-client :token "123"))
“‘
### Call api ###
With client and api, now we can call api in our code:
“‘lisp
;; call api with client and api we made before
(github-client:github-api-call *client-without-token*
*api-doc*)
;;; REPL will ask you to input ‘:username‘, ‘type‘, ‘sort‘, and ‘direction‘
;;; Then, it will return the dex:http-response, you can find this MULTIPLE-VALUEs
;;; return format in https://github.com/fukamachi/dexador#following-redirects-get-or-head
;; call POST method api with additional :content keyword
(github-client:github-api-call *client-without-token*
*api-doc*
:headers ’((header0 . value0) (header1 . value1))
:content "this argument pass to dexador directly")
“‘
‘github-api-call‘ will call api with the default headers ‘’(("Accept" . "application/vnd.github+json"))‘. Any other headers pass to ‘:headers‘ will been added ‘("Accept" . "application/vnd.github+json")‘.
From now, github-api-cl’s job is done, left all http response back to you, you can do whatever you want.
Wait, if you do not want REPL ask you to input every slots and parameters:
“‘lisp
(github-client:github-api-call *client-without-token*
*api-doc*
:username "lisp"
:type "public"
:direction "test"
:neither-slots-nor-parameter 1) ;; last keyword is redundant
“‘
With keywords input, REPL won’t ask you anything, just call ‘https://api.github.com/users/lisp/repos?type=\"public\"&direction=\"test\"‘.
As example shows, ‘:username‘ fills api slot, ‘:type‘ & ‘:direction‘ fill parameters, ‘:neither-slots-nor-parameter‘ is useless in this api.
For ‘POST‘ method api, ‘:content‘ is the keyword for add the content. It pass to ‘:content‘ keyword of ‘dexador‘’s ‘POST‘ [method](https://github.com/fukamachi/dexador#function-post).
### Authorization ###
**Token, user-name&passd**
When you need authorization, you can put ‘:token‘, ‘:user-name‘ and ‘:passd‘ in ‘github-client:github-api-call‘ as keywords.
Check logic is below :
+ If you input ‘:token‘, will use token you input
+ If no ‘:token‘ given but client has token already, it will use token stored in client
+ If neither ‘:token‘ nor client’s token is given, but has ‘:passd‘ keyword, will use ‘:user-name‘ & ‘passd‘ as authorization. (I just assume you give ‘:user-name‘ too, when you give ‘:passd‘)
0.3.1
str (system).
yason (system).
dexador (system).
woo (system).
clack (system).
alexandria (system).
cl-base64 (system).
api-doc.lisp (file).
client.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
github-api-cl/github-api-cl.asdgithub-api-cl (system).
github-api-cl/api-doc.lispgithub-api-cl (system).
api-doc (class).
http-method (reader method).
(setf http-method) (writer method).
initialize-instance (method).
make-api-doc-from-json (function).
make-call-parameters (method).
make-call-url (generic function).
print-object (method).
read-api-json (function).
*api-json-file-path* (special variable).
*api-root-url* (special variable).
api (reader method).
(setf api) (writer method).
coerce-parameter-type (function).
control-str (reader method).
(setf control-str) (writer method).
parameters (reader method).
(setf parameters) (writer method).
parse-api (function).
parse-keys (function).
slots (reader method).
(setf slots) (writer method).
github-api-cl/client.lispapi-doc.lisp (file).
github-api-cl (system).
api-client (class).
github-api-call (generic function).
http-call (generic function).
token (reader method).
(setf token) (writer method).
token-p (method).
token-p-or-input (method).
Packages are listed by definition order.
github-clientcommon-lisp.
github-api-doc.
api-client (class).
github-api-call (generic function).
http-call (generic function).
token (generic reader).
(setf token) (generic writer).
token-p (generic function).
token-p-or-input (generic function).
github-api-doccommon-lisp.
api-doc (class).
http-method (generic reader).
(setf http-method) (generic writer).
make-api-doc-from-json (function).
make-call-parameters (generic function).
make-call-url (generic function).
read-api-json (function).
*api-json-file-path* (special variable).
*api-root-url* (special variable).
api (generic reader).
(setf api) (generic writer).
coerce-parameter-type (function).
control-str (generic reader).
(setf control-str) (generic writer).
parameters (generic reader).
(setf parameters) (generic writer).
parse-api (function).
parse-keys (function).
slots (generic reader).
(setf slots) (generic writer).
Definitions are sorted by export status, category, package, and then by lexicographic order.
call with read-api-json usually
read json api file from *api-json-file-path*, return yason json object
api-client) (api api-doc) &rest args) ¶api-client) url &rest args &key method &allow-other-keys) ¶Return the url of this api http call
api-client)) ¶automatically generated reader method
api-client)) ¶automatically generated writer method
api-client)) ¶check if client has token
api-client)) ¶check if client has token, if not, ask to input
string
""
:token
string
cons
string
cons
:parameters
api json file path
give an api entry, return (method format-control slots)
for make parse keywords function, make flexible of keywords input
| Jump to: | (
A C F G H I M P R S T |
|---|
| Jump to: | (
A C F G H I M P R S T |
|---|
| Jump to: | *
A F H P S T |
|---|
| Jump to: | *
A F H P S T |
|---|
| Jump to: | A C F G P S |
|---|
| Jump to: | A C F G P S |
|---|