Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cyruzin/tome
Package tome was designed to paginate simple RESTful APIs.
https://github.com/cyruzin/tome
api go golang pagination rest restful
Last synced: 3 months ago
JSON representation
Package tome was designed to paginate simple RESTful APIs.
- Host: GitHub
- URL: https://github.com/cyruzin/tome
- Owner: cyruzin
- License: mit
- Created: 2019-04-12T16:49:45.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2022-04-20T16:41:33.000Z (over 2 years ago)
- Last Synced: 2024-06-19T03:08:25.179Z (5 months ago)
- Topics: api, go, golang, pagination, rest, restful
- Language: Go
- Homepage:
- Size: 121 KB
- Stars: 35
- Watchers: 2
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-go-extra - tome - 04-12T16:49:45Z|2022-04-20T16:41:33Z| (Utilities / Fail injection)
README
[](https://github.com/cyruzin/tome/actions/workflows/build.yml) [](https://coveralls.io/github/cyruzin/tome?branch=master) [](https://godoc.org/github.com/cyruzin/tome) [](https://goreportcard.com/report/github.com/cyruzin/tome) [](https://github.com/Naereen/StrapDown.js/blob/master/LICENSE)
Package tome was designed to paginate simple RESTful APIs.
## Installation
```sh
go get -u github.com/cyruzin/tome
```
## Usage
To get started, import the `tome` package and initiate the pagination:
```go
import "github.com/cyruzin/tome"
// Post type is a struct for a single post.
type Post struct {
Title string `json:"title"`
Body string `json:"body"`
}
// Posts type is a struct for multiple posts.
type Posts []*Post
// Result type is a struct of posts with pagination.
type Result struct {
Data *Posts `json:"data"`
*tome.Chapter
}
// GetPosts gets the latest 10 posts with pagination.
func GetPosts(w http.ResponseWriter, r *http.Request) {
// Creating a tome chapter with links.
chapter := &tome.Chapter{
// Setting base URL.
BaseURL: "http://yourapi.com/v1/posts",
// Enabling link results.
Links: true,
// Page that you captured in params inside you handler.
NewPage: 2,
// Total of pages, this usually comes from a SQL query total rows result.
TotalResults: model.GetPostsTotalResults(),
}
// Paginating the results.
if err := chapter.Paginate(); err != nil {
w.WriteHeader(http.StatusUnprocessableEntity) // Setting status 422.
json.NewEncoder(w).Encode(err) // Returning JSON with an error.
return
}
// Here you pass the offset and limit.
database, err := model.GetPosts(chapter.Offset, chapter.Limit)
if err != nil {
w.WriteHeader(http.StatusUnprocessableEntity) // Setting status 422.
json.NewEncoder(w).Encode(err) // Returning JSON with an error.
return
}
// Mocking results with pagination.
res := &Result{Data: database, Chapter: chapter}
w.WriteHeader(http.StatusOK) // Setting status 200.
json.NewEncoder(w).Encode(res) // Returning success JSON.
}
```
Output:
```json
{
"data": [
{
"title": "What is Lorem Ipsum?",
"body": "Lorem Ipsum is simply dummy text of the printing and..."
},
{
"title": "Why do we use it?",
"body": "It is a long established fact that a reader will be..."
}
],
"base_url": "http://yourapi.com/v1/posts",
"next_url": "http://yourapi.com/v1/posts?page=3",
"prev_url": "http://yourapi.com/v1/posts?page=1",
"per_page": 10,
"current_page": 2,
"last_page": 30,
"total_results": 300
}
```
## Performance
Without links:
| Iterations | ns/op | B/op | allocs/op |
|------------|-------|------|-----------|
| 200000000 | 7.80 | 0 | 0 |
With links:
| Iterations | ns/op | B/op | allocs/op |
|------------|-------|------|-----------|
| 10000000 | 133 | 96 | 2 |