Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/bndr/gopencils

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

Last synced: about 1 month ago
JSON representation

Easily consume REST APIs with Go (golang)

Lists

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