saferwall-api

saferwall web apis

Preface

This repository powers the web service api used in https://saferwall.com.

Vendoring

These packages are used in the project:

• Routing: Echo
• Configuration: viper
• Logging: zap
• Message queuing: nsq
• JSON Web Tokens jwt
• Couchbase Driver: gocb
• Password Hashing: bcrypt
• Data Validation: validator

Available Endpoints

The following endpoints are available:

• GET /healthcheck health check.

Activities

• GET /v1/activities returns a paginated list of activities.
• DELETE /v1/activities deletes multiple activities.

Authentication

• POST /v1/auth/login authenticates a user and generates a JWT.
• POST /v1/auth/confirm confirms an account from email token.
• POST /v1/auth/resend-confirmation re-send confirmation email.
• POST /v1/auth/reset-password send an email with a reset password token.
• update password given a token
• update password for logged in users
• update email
• update avatar

Users resource

• GET /v1/users: get a paginated list of users.
• POST /v1/users: creates a new user.
• PATCH /v1/users: update multiple users.
• PUT /v1/users: replace multiple users.
• DELETE /v1/users: deletes multiple users.

User resource

• GET /v1/users/:username: get a detailed information of a user.
• PATCH /v1/users/:username: updates an existing user.
• PUT /v1/users/:username: replaces an existing user.
• DELETE /v1/users/:username: deletes an existing user.
• GET /v1/users/:username/likes: get a paginated list of user's likes.
• GET /v1/users/:username/submissions: get a paginated list of user's submissions.
• GET /v1/users/:username/following: get a paginated list of user's following.
• GET /v1/users/:username/followers: get a paginated list of user's followers.
• GET /v1/users/:username/comments: get a paginated list of user's comments.
• GET /v1/users/:username/activities: get a paginated list of user's activities.

User actions

• POST /v1/users/:username/follow: follow an existing user.
• POST /v1/users/:username/unfollow: unfollow an existing user.

Files resource

• GET /v1/files: get a paginated list of files.
• POST /v1/files: creates a new file.
• PATCH /v1/files: update multiple files.
• PUT /v1/files: replace multiple files.
• DELETE /v1/files: deletes multiple files.

File resource

• GET /v1/files/:sha256: get a detailed information of a file.
• PATCH /v1/files/:sha256: updates an existing file.
• PUT /v1/files/:sha256: replaces an existing file.
• DELETE /v1/files/:sha256: deletes an existing file.
• GET /v1/files/:sha256: get a detailed information of a file.

File actions

• POST /v1/files/:sha256/like: likes an existing file.
• POST /v1/files/:sha256/unlike: unlike an existing file.
• POST /v1/files/:sha256/rescan: re-scan an existing file.

Comments resource

• GET /v1/comments returns a paginated list of comments.
• POST /v1/comments: creates a new comment.
• DELETE /v1/comments deletes multiple comments.

Comment resource

• GET /v1/comments/:id: get a detailed information of a comment.
• PATCH /v1/comments/:id: updates an existing comment.
• PUT /v1/comments/:id: replaces an existing comment.
• DELETE /v1/comments/:id: deletes an existing comment.

Rules for mapping HTTP methods to CRUD:

POST   - Create (add record into database)
GET    - Read (get record from the database)
PATCH  - Update (edit record in the database)
PUT    - Replace (replace record in the database)
DELETE - Delete (remove record from the database)

Rules for HTTP status codes:

* Create something            - 201 (Created)
* Read something              - 200 (OK)
* Update something            - 200 (OK)
* Delete something            - 200 (OK)
* Missing request information - 400 (Bad Request)
* Unauthorized operation      - 401 (Unauthorized)
* Any other error             - 500 (Internal Server Error)

Folder Structure

This project follows the Standard Go Project Layout

• build - contains packaging and Continuous Integration files.
• cmd - contains the main function.
• configs - contains configuration file templates or default configs.
• docs - contains design and user documents.
• internal - contains project specific packages with dependencies.
• pkg - contains generic packages without project specific dependencies - these can be safely moved to other projects without internal dependencies.

Improvements compared to the previous implementation

• clean architecture with solid principles.
• Full test coverage
• swagger doc
• Error handling with proper error response generation
• details:
  • File{} not depending on peparser.

References

• Standard Package Layout
• How Do You Structure Your Go Apps? by Kat Zień
• https://www.calhoun.io/moving-towards-domain-driven-design-in-go/
• Domain Driven Design in Golang - Strategic Design
• Idiometic Go Web Application Structure
• A clean architecture for Web Application in Go lang
• https://github.com/golang/go/wiki/CodeReviewComments
• https://golang.org/doc/effective_go
• https://peter.bourgon.org/go-best-practices-2016/
• https://www.youtube.com/watch?v=dp1cc6-QKY0