goshikimori

README

API Шикимори для Golang

Описание

Пакет предназначен для взаимодействия с API Шикимори.

Зависимости

• github.com/golang/oauth2
• github.com/seryiza/loadOAuth (пакет helpers)
• github.com/headzoo/surf

Установка

go get github.com/seryiza/goshikimori

Использование

OAuth2

Прежде всего, для OAuth2 потребуется создать приложение на самом Шикимори. Для авторизации потребуется название приложения, client id и client secret.

Работа с API

Объект goshikimori.Shikimori предназначен для взаимодействия с API Шикимори. Можно использовать через:

• HTTP-запросы Shikimori.Get/Post/...:

  // var shiki *goshikimori.Shikimori

  resp, _ := shiki.Get("users/whoami")    // для GET https://shikimori.org/api/users/whoami
  userJSON, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(userJSON))
  // => {"id":206253,"nickname":"Seryiza",...,"locale":"ru"}

• HTTP-запросы с приведением к структурам Shikimori.JSONGet/JSONPost/...:

// var shiki *goshikimori.Shikimori

var im structs.User
err := shiki.JSONGet("users/whoami", &im)
if err != nil {
  panic(err)
}

fmt.Println(im, err)
// => models.User{
//      ID: 206253,
//      Nickname: "Seryiza",
//      ...
//    }

Пример

Также есть примеры в папке examples.

conf := &oauth2.Config{
  ClientID:     "your shikimori client id",
  ClientSecret: "your shikimori client secret",
  RedirectURL:  auth.StandaloneRedirectURL,
  Endpoint:     auth.ShikimoriEndpoint,
}

url := auth.GetAuthCodeURL(conf)
fmt.Println("Enter code from here: ", url)

var code string
if _, err := fmt.Scanln(&code); err != nil {
  panic(err)
}

ctx := context.Background()
ctx = goshikimori.AddTransport(ctx, "your shikimori oauth app name")

tok, err := conf.Exchange(ctx, code)
if err != nil {
  panic(err)
}

client := conf.Client(ctx, tok)
shiki := goshikimori.NewShikimori(client, "1.0")  // 1.0 -- version of Shikimori API

resp, err := shiki.Get("users/whoami")
if err != nil {
  panic(err)
}

user := &structs.User{}
jd := json.NewDecoder(resp.Body)
if err = jd.Decode(user); err != nil {
  panic(err)
}

fmt.Printf("I'm %s", user.Nickname)

Также есть вспомогательные функции helpers (использующие файлы и env-переменные) для написания меньшего кода:

// GetShikimori получает oauth2 конфиг и токен из файлов или env-переменных
// и создает Shikimori из стандартного http клиента
shiki, err := helpers.GetShikimori("1.0")
if err != nil {
  panic(err)
}
// Сохраняем токен в файл, если он изменился
defer helpers.SaveToken(shiki)

user := &structs.User{}
_, err = shiki.JSONGet("users/whoami", user)
if err != nil {
  panic(err)
}

fmt.Printf("I'm %s", user.Nickname)

Тестирование

Тесты также проверяют запрос-ответ от Шикимори. Для корректной работы всех тестов необходимо задать следующие envirement-переменные:

• SHIKI_APP_NAME -- название OAuth-приложения на Шикимори
• SHIKI_CLIENTID -- публичный Client ID приложения на Шикимори
• SHIKI_CLIENTSECRET -- секретный ключ приложения на Шикимори
• SHIKI_REDIRECT_URL -- url для перенаправления приложения (на Шикимори)
• SHIKI_TOKEN_FILE -- путь к файлу с json-токеном
• SHIKI_CONF_FILE -- путь к файлу с json oauth-конфигурацией
• SHIKI_LOGIN -- псевдоним пользователя
• SHIKI_PASS -- пароль пользователя (используется при получении токена, если предыдущий был истекшим)

Documentation

Index

• func AddTransport(ctx context.Context, appName string) context.Context
• func FormatQuery(method string, values url.Values) string
• type Shikimori
  • func NewShikimori(client *http.Client, version string) *Shikimori
  • func (shiki *Shikimori) Delete(method string) (*http.Response, error)
  • func (shiki *Shikimori) Do(req *http.Request) (*http.Response, error)
  • func (shiki *Shikimori) Get(method string) (*http.Response, error)
  • func (shiki *Shikimori) JSONGet(method string, outStruct interface{}) (*http.Response, error)
  • func (shiki *Shikimori) JSONPost(method string, inStruct, outStruct interface{}) (*http.Response, error)
  • func (shiki *Shikimori) NewRequest(httpMethod, shikiMethod string, body io.Reader) (*http.Request, error)
  • func (shiki *Shikimori) Patch(method string, body io.Reader) (*http.Response, error)
  • func (shiki *Shikimori) Post(method string, body io.Reader) (*http.Response, error)
  • func (shiki *Shikimori) Put(method string, body io.Reader) (*http.Response, error)
• type Transport
  • func (tr Transport) RoundTrip(req *http.Request) (*http.Response, error)

Functions

func AddTransport

func AddTransport(ctx context.Context, appName string) context.Context

AddTransport to context. If ctx.Value(oauth2.HTTPClient) == nil, then using DefaultTransport + Shikimori Transport

func FormatQuery

func FormatQuery(method string, values url.Values) string

FormatQuery returns Shikimori method with HTTP GET values. Ex., "users", {"limit": 100} => "users?limit=100"

Types

type Shikimori

type Shikimori struct {
	Client *http.Client

	// URLFormat of format template for Shikimori API
	URLFormat string
	Version   string
}

Shikimori to send requests to Shikimori API

func NewShikimori

func NewShikimori(client *http.Client, version string) *Shikimori

func (*Shikimori) Delete

func (shiki *Shikimori) Delete(method string) (*http.Response, error)

Delete Shikimori method (HTTP DELETE request)

func (*Shikimori) Do

func (shiki *Shikimori) Do(req *http.Request) (*http.Response, error)

Do http request. If returns 404, return as error (for comfy use)

func (*Shikimori) Get

func (shiki *Shikimori) Get(method string) (*http.Response, error)

Get Shikimori method (HTTP GET request)

func (*Shikimori) JSONGet

func (shiki *Shikimori) JSONGet(method string, outStruct interface{}) (*http.Response, error)

JSONGet Shikimori method (HTTP GET request + decode json into outStruct)

func (*Shikimori) JSONPost

func (shiki *Shikimori) JSONPost(method string, inStruct, outStruct interface{}) (*http.Response, error)

JSONPost Shikimori method (HTTP POST request + encode json from inStruct as body + decode json into outStruct)

func (*Shikimori) NewRequest

func (shiki *Shikimori) NewRequest(httpMethod, shikiMethod string, body io.Reader) (*http.Request, error)

NewRequest returns request for Shikimori (add to method full address). Ex., ("GET", "whoami", nil) => ("GET", "https://shikimori.org/api/whoami", nil)

func (*Shikimori) Patch

func (shiki *Shikimori) Patch(method string, body io.Reader) (*http.Response, error)

Patch Shikimori method (HTTP PATCH request)

func (*Shikimori) Post

func (shiki *Shikimori) Post(method string, body io.Reader) (*http.Response, error)

Post Shikimori method (HTTP POST request)

func (*Shikimori) Put

func (shiki *Shikimori) Put(method string, body io.Reader) (*http.Response, error)

Put Shikimori method (HTTP PUT request)

type Transport

type Transport struct {
	// As User-Agent for Shikimori
	ApplicationName string
	Target          http.RoundTripper
}

Transport for adding headers

func (Transport) RoundTrip

func (tr Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements RoundTripper. Set User-Agent and call Transport.Target