jemuelmiao/restful

jemuelmiao/restful

A package based on Golang and MongoDB for quickly building HTTP RESTful services with JSON.

Required

• go 1.13+
• mongodb v3.4.x v3.6.x
• elasticsearch v6.8.x v7.x.x (if enable searching)

Installation

Use go get.

go get github.com/jemuelmiao/restful

Then import the package into your own code.

import "github.com/jemuelmiao/restful"

Feature Overview

• Define the structure of the data resource (including json and bson tags), then you can implement the CURD service of HTTP+JSON. The protocol is as follows:

HTTP Method	Path	URL Params	HTTP Body	Explain
POST	/{biz}	-	data to be inserted	insert data
PUT	/{biz}/{id}	-	data to be upserted	insert or update(overwrite) data by id
PATCH	/{biz}/{id}	seq	data to be updated	update data by id
DELETE	/{biz}/{id}	-	-	delete data by id
GET	/{biz}/{id}	-	-	get data by id
GET	/{biz}	page size filter range in nin all search order select	-	get list of data: page=1 size=10 filter={"star":5, "city":"shenzhen"} range={"age":{"gt":20, "lt":40}} in={"color":["blue", "red"]} nin={"color":["blue", "red"]} all={"color":["blue", "red"]} search=hello order=["+age", "-time"] select=["id", "name", "age"]

• When defining a data resource structure, the supported data types include:

  common types: bool int32 uint32 int64 uint64 float32 float64 string struct
  array types: []bool []int32 []uint32 []int64 []uint64 []float32 []float64 []string []struct
  map types: map[string]bool map[string]int32 map[string]uint32 map[string]int64 map[string]uint64 map[string]float32 map[string]float64 map[string]string  map[string]struct

• Support field level CreateOnly or ReadOnly:

  • CreateOnly: only allows creation, does not allow subsequent modification of the field
  • ReadOnly: only allows reading, does not allow creation and modification, is suitable for importing data from other systems to the database, and then providing data reading services.

• With the field check function, the incoming data field type is wrong or does not exist, it will return a failure and prompt specific error information.

• Support custom data ID or automatically create ID (UUIDv4), pay attention to the writing of tags:

    type Foo struct {
        Id  *string  `json:"id,omitempty" bson:"_id,omitempty"`
        ...
    }

• Support tracking data birth time and modify time, two additional fields required:

  • btime: birth time, record the timestamp when data created
  • mtime: modify time, record the timestamp the last modification of data

• Support anti-concurrent writing, the seq field required:

  • seq: will be updated each time the data is modified, the update (PATCH) request needs to bring the data original seq to prevent concurrent writing from causing data confusion.

• Support custom database name and table name, with URL params:

  • db: database name, default is restful
  • table: table name, default is {Biz}

  e.g.: /{Biz}?db=dbName&table=tableName

How to use

See examples. We take the Student of simple.go as an example:

Insert resource (with or without id)

Request:

POST /student HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 226

{
    "id": "student-id-001",
    "name": "jemuelmiao",
    ...
}

Response:

HTTP/1.1 200 OK
Date: Mon, 22 Apr 2019 06:46:23 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 91

{
    "code": 0,
    "msg": "post ok",
    "data": {
        "id": "student-id-001"
    }
}

Upsert resource by id

Request:

PUT /student/student-id-001 HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 226

{
    "id": "student-id-001",
    "name": "jemuelmiao",
    ...
}

Response:

HTTP/1.1 200 OK
Date: Mon, 22 Apr 2019 06:46:23 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 90

{
    "code": 0,
    "msg": "put ok",
    "data": {
        "id": "student-id-001"
    }
}

Update resource by id

Request:

PATCH /student/student-id-001?seq=1 HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 226

{
    "id": "student-id-001",
    "name": "jemuelmiao02",
    ...
}

Response:

HTTP/1.1 200 OK
Date: Mon, 22 Apr 2019 06:46:23 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 30

{
    "code": 0,
    "msg": "patch ok",
    "data": {
        "id": "student-id-001"
    }
}

Delete resource by id

Request:

DELETE /student/student-id-001 HTTP/1.1

Response:

HTTP/1.1 200 OK
Date: Mon, 22 Apr 2019 06:46:23 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 30

{
    "code": 0,
    "msg": "delete ok",
    "data": {
        "id": "student-id-001"
    }
}

Get resource by id

Request:

GET /student/student-id-001 HTTP/1.1

Response:

HTTP/1.1 200 OK
Date: Mon, 22 Apr 2019 06:46:23 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 537

{
    "code": 0,
    "msg": "get ok",
    "data": {
        "id": "student-id-001"
        "name": "jemuelmiao",
        ...
    }
}

Get resources

Request:

GET /student?page=1&size=10 HTTP/1.1

Response:

HTTP/1.1 200 OK
Date: Mon, 22 Apr 2019 06:46:23 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 797

{
    "code": 0,
    "msg": "get page ok",
    "data": {
        "total": 238,
        "hits": [
            {
                "id": "student-id-001",
                "name": "jemuelmiao",
                ...
            },
            {
                "id": "student-id-002",
                "name": "tonywho",
                ...
            }
            ...
        ]
    }
}