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/verify/: 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.

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.
• PATCH /v1/users/:username/password/: updates an authenticated user's password.
• 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.
• POST /v1/users/:username/avatar/: updates an existing user's avatar.

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.

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.
• GET /v1/files/:sha256/download/: downloads 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