https://github.com/bndr/gopencils

Easily consume REST APIs with Go (golang)
https://github.com/bndr/gopencils

Last synced: 3 months ago
JSON representation

Easily consume REST APIs with Go (golang)

• Host: GitHub
• URL: https://github.com/bndr/gopencils
• Owner: bndr
• License: apache-2.0
• Created: 2014-06-23T11:41:24.000Z (over 10 years ago)
• Default Branch: master
• Last Pushed: 2019-02-18T01:03:37.000Z (over 5 years ago)
• Last Synced: 2024-07-31T01:29:38.565Z (3 months ago)
• Language: Go
• Homepage:
• Size: 44.9 KB
• Stars: 452
• Watchers: 14
• Forks: 40
• Open Issues: 7
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.md

Awesome Lists containing this project

• awesome-rest - gopencils - Small and simple package to easily consume REST APIs. (Clients / Go Clients)
• awesome-go - gopencils - Easily consume REST APIs with Go (golang) - ★ 414 (Utilities)
• awesome-go-extra - gopencils - 06-23T11:41:24Z|2019-02-18T01:03:37Z| (Utilities / Fail injection)

README

        
# Gopencils - Dynamically consume REST APIs

[![GoDoc](https://godoc.org/github.com/bndr/gopencils?status.svg)](https://godoc.org/github.com/bndr/gopencils)

[![Build Status](https://travis-ci.org/bndr/gopencils.svg?branch=master)](https://travis-ci.org/bndr/gopencils)

## Summary

Gopencils is a REST Client written in go. Easily consume any REST API's. Supported Response formats: JSON

## Install

    go get github.com/bndr/gopencils

## Simple to use

Gopencils was designed to help you easily make requests to REST APIs without much hassle. It supports both Basic-Auth as well as OAuth.

Example Basic-Auth

```go

type UserExample struct {

	Id            string

	Name          string

	Origin        string

	Url           string

	SomeJsonField string

}

// Create Basic Auth

auth := gopencils.BasicAuth{"username", "password"}

// Create New Api with our auth

api := gopencils.Api("http://your-api-url.com/api/", &auth)

// Create a pointer to our response struct

resp := &UserExample{}

// Perform a GET request

// URL Requested: http://your-api-url.com/api/users/1

api.Res("users", resp).Id(1).Get()

// Get Single Item

api.Res("users", resp).Id(1).Get()

// Perform a GET request with Querystring

querystring := map[string]string{"page": "100", "per_page": "1000"}

// URL Requested: http://your-api-url.com/api/users/123/items?page=100&per_page=1000

resource := api.Res("users").Id(123).Res("items", resp).Get(querystring)

// Now resp contains the returned json object

// resource.Raw contains raw http response,

// You can supply Path suffix to the api which will be applied to every url

// e.g /items/id.json

api := gopencils.Api("http://your-api-url.com/api/", &auth, ".json")

```

Example Github Api

```go

package main

import (

	"fmt"

	"github.com/bndr/gopencils"

)

type respStruct struct {

	Login string

	Id    int

	Name  string

}

func main() {

	api := gopencils.Api("https://api.github.com")

	// Users Resource

	users := api.Res("users")

	usernames := []string{"bndr", "torvalds", "coleifer"}

	for _, username := range usernames {

		// Create a new pointer to response Struct

		r := new(respStruct)

		// Get user with id i into the newly created response struct

		_, err := users.Id(username, r).Get()

		if err != nil {

			fmt.Println(err)

		} else {

			fmt.Println(r)

		}

	}

}

```

More examples in the examples folder.

## Why?

I work a lot with REST APIs and I caught myself writing the same code over and over, so I decided to make a library that would help me (and others) to quickly consume them.

## Is it ready?

It is still in beta. But I would be glad if you could test it on your pet projects. The API will be improved, but no breaking changes are planned.

## Contribute

All Contributions are welcome. The todo list is on the bottom of this README. Feel free to send a pull request.

## License

Apache License 2.0

## TODO

1. Add more Options (Flexibility)

2. Support XML Response

3. Better Error Handling