The github-api-cl Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The github-api-cl Reference Manual

This is the github-api-cl Reference Manual, version 0.3.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 04:41:53 2022 GMT+0.

Table of Contents


1 Introduction

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

Usage

You can check ./example

Dependencies

I use yason for json parser, 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:

{
    "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:

;; 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:

;; 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:

{
  "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:

;; 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:

;; 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*
                               :content "this argument pass to dexador directly")

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:

(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.

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 :


2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 github-api-cl

The lite Github rest v3 api client SDK

Maintainer

ccQpein

Author

ccQpein

Home Page

https://github.com/ccqpein/Github-API-CL

Source Control

(GIT git@github.com:ccqpein/Github-API-CL.git)

Bug Tracker

https://github.com/ccqpein/Github-API-CL/issues

License

Apache

Long Description

# 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*
:content "this argument pass to dexador directly")
“‘

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‘)

Version

0.3.0

Defsystem Dependencies
  • str (system).
  • yason (system).
  • dexador (system).
  • woo (system).
  • clack (system).
  • alexandria (system).
  • cl-base64 (system).
Source

github-api-cl.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.1 github-api-cl/github-api-cl.asd

Source

github-api-cl.asd.

Parent Component

github-api-cl (system).

ASDF Systems

github-api-cl.

Packages

github-api-cl-sys.


3.1.2 github-api-cl/api-doc.lisp

Source

github-api-cl.asd.

Parent Component

github-api-cl (system).

Packages

github-api-doc.

Public Interface
Internals

3.1.3 github-api-cl/client.lisp

Dependency

api-doc.lisp (file).

Source

github-api-cl.asd.

Parent Component

github-api-cl (system).

Packages

github-client.

Public Interface

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 github-api-cl-sys

Source

github-api-cl.asd.

Use List
  • asdf/interface.
  • common-lisp.

4.2 github-client

Source

client.lisp.

Use List
Public Interface

Previous: , Up: Packages   [Contents][Index]

4.3 github-api-doc

Source

api-doc.lisp.

Use List

common-lisp.

Used By List

github-client.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


5.1.1 Ordinary functions

Function: make-api-doc-from-json (json-obj &rest paths)

call with read-api-json usually

Package

github-api-doc.

Source

api-doc.lisp.

Function: read-api-json (&optional file-path)

read json api file from *api-json-file-path*, return yason json object

Package

github-api-doc.

Source

api-doc.lisp.


5.1.2 Generic functions

Generic Function: github-api-call (client api &rest args &key &allow-other-keys)
Package

github-client.

Source

client.lisp.

Methods
Method: github-api-call ((clt api-client) (api api-doc) &rest args)
Generic Function: http-call (client url &rest args &key method &allow-other-keys)
Package

github-client.

Source

client.lisp.

Methods
Method: http-call ((clt api-client) url &rest args &key method &allow-other-keys)
Generic Reader: http-method (object)
Package

github-api-doc.

Methods
Reader Method: http-method ((api-doc api-doc))

automatically generated reader method

Source

api-doc.lisp.

Target Slot

http-method.

Generic Writer: (setf http-method) (object)
Package

github-api-doc.

Methods
Writer Method: (setf http-method) ((api-doc api-doc))

automatically generated writer method

Source

api-doc.lisp.

Target Slot

http-method.

Generic Function: make-call-parameters (api &rest args &key &allow-other-keys)
Package

github-api-doc.

Methods
Method: make-call-parameters ((api api-doc) &rest args &key &allow-other-keys)
Source

api-doc.lisp.

Generic Function: make-call-url (api &rest args &key root &allow-other-keys)

Return the url of this api http call

Package

github-api-doc.

Source

api-doc.lisp.

Methods
Method: make-call-url ((api api-doc) &rest args &key root &allow-other-keys)

make the url of this api ask user to input data and return call url

Generic Reader: token (object)
Package

github-client.

Methods
Reader Method: token ((api-client api-client))

automatically generated reader method

Source

client.lisp.

Target Slot

token.

Generic Writer: (setf token) (object)
Package

github-client.

Methods
Writer Method: (setf token) ((api-client api-client))

automatically generated writer method

Source

client.lisp.

Target Slot

token.

Generic Function: token-p (clt)
Package

github-client.

Methods
Method: token-p ((clt api-client))

check if client has token

Source

client.lisp.

Generic Function: token-p-or-input (clt)
Package

github-client.

Methods
Method: token-p-or-input ((clt api-client))

check if client has token, if not, ask to input

Source

client.lisp.


5.1.3 Standalone methods

Method: initialize-instance :after ((api api-doc) &key)
Source

api-doc.lisp.

Method: print-object ((api api-doc) stream)
Source

api-doc.lisp.


5.1.4 Classes

Class: api-client
Package

github-client.

Source

client.lisp.

Direct methods
Direct slots
Slot: token
Type

string

Initform

""

Initargs

:token

Readers

token.

Writers

(setf token).

Class: api-doc
Package

github-api-doc.

Source

api-doc.lisp.

Direct methods
Direct slots
Slot: api
Type

string

Initargs

:api

Readers

api.

Writers

(setf api).

Slot: http-method
Type

string

Readers

http-method.

Writers

(setf http-method).

Slot: slots
Type

cons

Readers

slots.

Writers

(setf slots).

Slot: fmt-control
Type

string

Readers

control-str.

Writers

(setf control-str).

Slot: parameters
Type

cons

Initargs

:parameters

Readers

parameters.

Writers

(setf parameters).


5.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.1 Special variables

Special Variable: *api-json-file-path*

api json file path

Package

github-api-doc.

Source

api-doc.lisp.

Special Variable: *api-root-url*
Package

github-api-doc.

Source

api-doc.lisp.


5.2.2 Ordinary functions

Function: coerce-parameter-type (ss type-ss)
Package

github-api-doc.

Source

api-doc.lisp.

Function: parse-api (str)

give an api entry, return (method format-control slots)

Package

github-api-doc.

Source

api-doc.lisp.

Function: parse-keys (args)

for make parse keywords function, make flexible of keywords input

Package

github-api-doc.

Source

api-doc.lisp.


5.2.3 Generic functions

Generic Reader: api (object)
Package

github-api-doc.

Methods
Reader Method: api ((api-doc api-doc))

automatically generated reader method

Source

api-doc.lisp.

Target Slot

api.

Generic Writer: (setf api) (object)
Package

github-api-doc.

Methods
Writer Method: (setf api) ((api-doc api-doc))

automatically generated writer method

Source

api-doc.lisp.

Target Slot

api.

Generic Reader: control-str (object)
Package

github-api-doc.

Methods
Reader Method: control-str ((api-doc api-doc))

automatically generated reader method

Source

api-doc.lisp.

Target Slot

fmt-control.

Generic Writer: (setf control-str) (object)
Package

github-api-doc.

Methods
Writer Method: (setf control-str) ((api-doc api-doc))

automatically generated writer method

Source

api-doc.lisp.

Target Slot

fmt-control.

Generic Reader: parameters (object)
Package

github-api-doc.

Methods
Reader Method: parameters ((api-doc api-doc))

automatically generated reader method

Source

api-doc.lisp.

Target Slot

parameters.

Generic Writer: (setf parameters) (object)
Package

github-api-doc.

Methods
Writer Method: (setf parameters) ((api-doc api-doc))

automatically generated writer method

Source

api-doc.lisp.

Target Slot

parameters.

Generic Reader: slots (object)
Package

github-api-doc.

Methods
Reader Method: slots ((api-doc api-doc))

automatically generated reader method

Source

api-doc.lisp.

Target Slot

slots.

Generic Writer: (setf slots) (object)
Package

github-api-doc.

Methods
Writer Method: (setf slots) ((api-doc api-doc))

automatically generated writer method

Source

api-doc.lisp.

Target Slot

slots.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
A   C   F   G   H   I   M   P   R   S   T  
Index Entry  Section

(
(setf api): Private generic functions
(setf api): Private generic functions
(setf control-str): Private generic functions
(setf control-str): Private generic functions
(setf http-method): Public generic functions
(setf http-method): Public generic functions
(setf parameters): Private generic functions
(setf parameters): Private generic functions
(setf slots): Private generic functions
(setf slots): Private generic functions
(setf token): Public generic functions
(setf token): Public generic functions

A
api: Private generic functions
api: Private generic functions

C
coerce-parameter-type: Private ordinary functions
control-str: Private generic functions
control-str: Private generic functions

F
Function, coerce-parameter-type: Private ordinary functions
Function, make-api-doc-from-json: Public ordinary functions
Function, parse-api: Private ordinary functions
Function, parse-keys: Private ordinary functions
Function, read-api-json: Public ordinary functions

G
Generic Function, (setf api): Private generic functions
Generic Function, (setf control-str): Private generic functions
Generic Function, (setf http-method): Public generic functions
Generic Function, (setf parameters): Private generic functions
Generic Function, (setf slots): Private generic functions
Generic Function, (setf token): Public generic functions
Generic Function, api: Private generic functions
Generic Function, control-str: Private generic functions
Generic Function, github-api-call: Public generic functions
Generic Function, http-call: Public generic functions
Generic Function, http-method: Public generic functions
Generic Function, make-call-parameters: Public generic functions
Generic Function, make-call-url: Public generic functions
Generic Function, parameters: Private generic functions
Generic Function, slots: Private generic functions
Generic Function, token: Public generic functions
Generic Function, token-p: Public generic functions
Generic Function, token-p-or-input: Public generic functions
github-api-call: Public generic functions
github-api-call: Public generic functions

H
http-call: Public generic functions
http-call: Public generic functions
http-method: Public generic functions
http-method: Public generic functions

I
initialize-instance: Public standalone methods

M
make-api-doc-from-json: Public ordinary functions
make-call-parameters: Public generic functions
make-call-parameters: Public generic functions
make-call-url: Public generic functions
make-call-url: Public generic functions
Method, (setf api): Private generic functions
Method, (setf control-str): Private generic functions
Method, (setf http-method): Public generic functions
Method, (setf parameters): Private generic functions
Method, (setf slots): Private generic functions
Method, (setf token): Public generic functions
Method, api: Private generic functions
Method, control-str: Private generic functions
Method, github-api-call: Public generic functions
Method, http-call: Public generic functions
Method, http-method: Public generic functions
Method, initialize-instance: Public standalone methods
Method, make-call-parameters: Public generic functions
Method, make-call-url: Public generic functions
Method, parameters: Private generic functions
Method, print-object: Public standalone methods
Method, slots: Private generic functions
Method, token: Public generic functions
Method, token-p: Public generic functions
Method, token-p-or-input: Public generic functions

P
parameters: Private generic functions
parameters: Private generic functions
parse-api: Private ordinary functions
parse-keys: Private ordinary functions
print-object: Public standalone methods

R
read-api-json: Public ordinary functions

S
slots: Private generic functions
slots: Private generic functions

T
token: Public generic functions
token: Public generic functions
token-p: Public generic functions
token-p: Public generic functions
token-p-or-input: Public generic functions
token-p-or-input: Public generic functions

Jump to:   (  
A   C   F   G   H   I   M   P   R   S   T