How To Code Go Part 5: HTTP And GRPC Format

Introduction

This document provides a design guide for HTTP and gRPC API. By following these conventions, we can make our API definitions more readable, and easier to maintain and detect errors.

that suggested for dev

Rule	Description
Path Naming Convention	Use underscore_separated_names for path names.
Field Naming Convention	Uniformly use underscore_separated_names or MixCaps for field names.
HTTP Status Codes	Follow these definitions for HTTP response status codes:
200	The request has been processed, but the success or failure is indicated by the response body.
400	Bad request parameter (e.g., missing parameter or parameter type mismatch).
401	Unauthorized (e.g., no permission, invalid cookie).
422	Unprocessable entity (Request is syntactically correct, but semantically invalid).
429	Too many requests (rate limit exceeded).
500	Server exception (e.g., DB error, internal server error).
503	The server is temporarily unable to handle the request.
504	Gateway timeout.
Standard JSON Response Structure	Use the following structure for all responses:
Response Body Example	json { "code": 0, "msg": "success", "data": { /* business data */ } }
Logical Error Response	Use code != 0 and HTTP status code 200 or 422 for logical errors.
Logical Error Example	json { "code": 10000, "msg": "exceed user’s backpack size limit", "data": {} }
API Consistency with YAPI	The API must match the definitions in YAPI, including path, field name, type, optionality, and comments.
Field Type - Integer vs. Float	Do not use float type fields, use integer instead.
RESTful API Methods	Use the correct HTTP methods for RESTful APIs: GET, POST, PUT, DELETE, etc.
Empty List vs. Null List	If the response contains a list, return an empty list [] instead of a null list.
Error Code Range	To make error detection easier, define fixed ranges of error codes for each business module:
10000~20000	Access errors
20001~30000	System errors
30001~40000	Chance module errors
40001~50000	LDC module errors
Restful API for Simple Logic	Use RESTful style APIs for resource-based services with simple logic.
RESTful Example	GET /redeem/api/v1/stores/:store_id (query a store) . POST /redeem/api/v1/stores/:store_id (create a store)
Custom API for Complex Logic	For complex scenarios, use JSON API with custom names, matching RPC request protocol for future ease of access.
JSON API Example	GET /pet/api/v1/game/round?round_num={round_num} (query a game round detail) . POST /pet/api/v1/game/begin_round (begin a game round)
Integer Precision	To avoid precision issues in JavaScript, integer fields with more than 52 bits should use string type (user_id, shop_id, timestamp will not exceed 52 bits).

gRPC API

Rule	Description
File and Package Naming	MUST: File names and package names should be named lower_snake_case. Example: package gameplatform_chance;
Message Naming	MUST: Use CamelCase for message names. Example: message SongServerRequest
Field Naming	MUST: Use underscore_separated_name for field names. `
gRPC Service and Method Naming	MUST: Use CamelCase for both the service name and any gRPC method names. Example: . protobuf <br />. service FooService { <br />. rpc GetSomething(GetSomethingRequest) returns (GetSomethingResponse); <br />. rpc ListSomething(ListSomethingRequest) returns (ListSomethingResponse); <br />. } <br />.
Field Types for Unique IDs	MUST: Use uint64/int64 for fields representing unique identifiers (e.g., user_id, shop_id, order_id, item_id).
Enumeration Definitions	MUST: If there is an enumeration, it should be defined in the .proto file. Example: . protobuf <br />. enum MsgSource { <br />. IOS = 3000; // apple msg source <br />. ANDROID = 4000; // android msg source <br />. } <br />. message SendChatRequest { <br />. optional MsgSource msg_source = 1; // refer to MsgSource <br />. ... <br />. } <br />.
Field Numbering	MUST: DO NOT change the field numbers for any existing fields.
Type Conversion	MUST: DO NOT do incompatible type conversions (e.g., int <-> string <-> float).
Response Message with List	RECOMMENDED: If a gRPC proto response message contains a field with type list (repeated), return nil or null list instead of an empty list. Note: This is different from HTTP response behavior.
Repeated Field Naming	RECOMMENDED: Use pluralized names for repeated fields. Example: accounts for a list of accounts, keys for a list of keys, values for a list of values.
Enum Naming	RECOMMENDED: Use CamelCase for enum type names and CAPITALS_WITH_UNDERSCORES for enum values. Example: . protobuf <br />. enum FooBar { <br />. FOO_BAR_UNSPECIFIED = 0; <br />. FOO_BAR_FIRST_VALUE = 1; <br />. FOO_BAR_SECOND_VALUE = 2; <br />. } <br />.
Keyword Usage	RECOMMENDED: DO NOT use require keyword, as it may cause compatibility issues.
Field Deletion	RECOMMENDED: DO NOT delete any existing fields; instead, use // deprecated since v1.x.y comments.
existing fields; instead, use // deprecated since v1.x.y comments.