Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cocoonspace/dynjson
Client-customizable JSON formats for dynamic APIs
https://github.com/cocoonspace/dynjson
Last synced: 3 months ago
JSON representation
Client-customizable JSON formats for dynamic APIs
- Host: GitHub
- URL: https://github.com/cocoonspace/dynjson
- Owner: cocoonspace
- License: mit
- Created: 2020-05-06T07:10:02.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-04-12T06:38:51.000Z (almost 2 years ago)
- Last Synced: 2024-07-30T20:43:28.718Z (6 months ago)
- Language: Go
- Homepage:
- Size: 43 KB
- Stars: 16
- Watchers: 2
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-go - dynjson - Client-customizable JSON formats for dynamic APIs. (JSON / Search and Analytic Databases)
- awesome-ccamel - cocoonspace/dynjson - Client-customizable JSON formats for dynamic APIs (Go)
- awesome-go-extra - dynjson - customizable JSON formats for dynamic APIs|12|5|0|2020-05-06T07:10:02Z|2021-10-11T15:25:37Z| (JSON / Advanced Console UIs)
README
# dynjson [](https://pkg.go.dev/github.com/cocoonspace/dynjson) [](https://app.travis-ci.com/github/cocoonspace/dynjson) [](https://coveralls.io/github/cocoonspace/dynjson?branch=master) [](https://goreportcard.com/report/github.com/cocoonspace/dynjson)
Client-customizable JSON formats for dynamic APIs.
## Introduction
dynjson allow APIs to return only fields selected by the API client:
```
GET https://api.example.com/v1/foos
[{"id":1,foo":1,"bar":2,"baz":3}]
GET https://api.example.com/v1/foos?select=foo
[{"foo":1}]
GET https://api.example.com/v1/foos/1?select=foo
{"foo":1}
```
dynjson mimicks the original struct using the original types and json tags.
The field order is the same as the select parameters.
## Installation
go get github.com/cocoonspace/dynjson
## Examples
```go
type APIResult struct {
Foo int `json:"foo"`
Bar string `json:"bar"`
}
f := dynjson.NewFormatter()
res := &APIResult{Foo:1, Bar:"bar"}
o, err := f.Format(res, dynjson.FieldsFromRequest(r))
if err != nil {
// handle error
}
err = json.NewEncoder(w).Encode(o) // {"foo": 1}
```
With struct fields:
```go
type APIResult struct {
Foo int `json:"foo"`
Bar APIIncluded `json:"bar"`
}
type APIIncluded struct {
BarFoo int `json:"barfoo"`
BarBar string `json:"barbar"`
}
f := dynjson.NewFormatter()
res := &APIResult{Foo: 1, Bar: APIIncluded{BarFoo:1, BarBar: "bar"}}
o, err := f.Format(res, []string{"foo", "bar.barfoo"})
if err != nil {
// handle error
}
err = json.NewEncoder(w).Encode(o) // {"foo": 1, "bar":{"barfoo": 1}}
```
With slices:
```go
type APIResult struct {
Foo int `json:"foo"`
Bar string `json:"bar"`
}
f := dynjson.NewFormatter()
res := []APIResult{{Foo: 1, Bar: "bar"}}
o, err := f.Format(res, []string{"foo"})
if err != nil {
// handle error
}
err = json.NewEncoder(w).Encode(o) // [{"foo": 1}]
```
```go
type APIResult struct {
Foo int `json:"foo"`
Bar []APIItem `json:"bar"`
}
type APIItem struct {
BarFoo int `json:"barfoo"`
BarBar string `json:"barbar"`
}
f := dynjson.NewFormatter()
res := &APIResult{Foo: 1, Bar: []APIItem{{BarFoo: 1, BarBar: "bar"}}}
o, err := f.Format(res, []string{"foo", "bar.barfoo"})
if err != nil {
// handle error
}
err = json.NewEncoder(w).Encode(o) // {"foo": 1, "bar":[{"barfoo": 1}]}
```
## Limitations
* Anonymous fields without a json tag (embedded by the Go JSON encoder in the enclosing struct) are not supported,
* Maps are copied as is, you cannot filter map contents using `map_field_name.map_key`.
## Performance impact
```
BenchmarkFormat_Fields
BenchmarkFormat_Fields-8 2466639 480 ns/op 184 B/op 7 allocs/op
BenchmarkFormat_NoFields
BenchmarkFormat_NoFields-8 5255031 232 ns/op 32 B/op 1 allocs/op
BenchmarkRawJSON
BenchmarkRawJSON-8 5351313 223 ns/op 32 B/op 1 allocs/op
```
## Contribution guidelines
Contributions are welcome, as long as:
* unit tests & comments are included,
* no external package is used.
## License
MIT - See LICENSE