diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f21b277a..9370c720 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,5 @@ # Contributing -Thank you for your interest in contributing to out project. The following are guidelines on how to best contribute to development of the HackIllinois API. Any contibution, wheather it be a bug report, feature request, bug fix, feature addition, or additional documentation, is greatly appreciated. +Thank you for your interest in contributing to out project. The following are guidelines on how to best contribute to development of the HackIllinois API. Any contribution, wheather it be a bug report, feature request, bug fix, feature addition, or additional documentation, is greatly appreciated. 1. [How to Contribute](#how-to-contribute) 2. [Styleguides](#styleguides) @@ -25,7 +25,7 @@ Feature suggestions include everything from minor improvements to adding complet - An explanation of why this feature would be useful ### Pull Requests -Take a look at the GitHub issues and leave a comment on one that you would like to work on. We have tagged some issues as `beginner` that are a good introduction to working on the API. Once you have made the appropiate changes open a pull request. +Take a look at the GitHub issues and leave a comment on one that you would like to work on. We have tagged some issues as `beginner` that are a good introduction to working on the API. Once you have made the appropiate changes, open a pull request. #### What to Include in a Pull Request - The base branch set to `staging` diff --git a/README.md b/README.md index 1639f5b2..a0814223 100644 --- a/README.md +++ b/README.md @@ -11,10 +11,10 @@ This repository contains the code which runs the backend services supporting Hac 5. [Documentation](#documentation) ## Developer Environment Setup -In order to work on the API there are a few setups neccessary in order to setup your developer environemnt. +In order to work on the API there are a few steps neccessary in order to setup your developer environemnt. ### Installing Dependencies -We highly reccommend that you use Ubuntu 18.04 when working on API development. The API is written and Go and makes use of MongoDB for storing data. You will have to install both of these before working on the API. You will also need a few common development tools including `make` and `git`. +We highly reccommend that you use Ubuntu when working on API development. The API is written in Go and makes use of MongoDB for storing data. You will have to install both of these before working on the API. You will also need a few common development tools including `make` and `git`. #### Installing Development Tools Both `make` and `git` can be installed from the default ubuntu package repositories. Run the following commands to install both tools. You may need to run the commands under `sudo`. @@ -30,7 +30,7 @@ Follow the [Go Installation Instructions](https://golang.org/doc/install#install Follow the [MongoDB Installation Instructions](https://docs.mongodb.com/manual/installation/#mongodb-community-edition) for installing MongoDB. Once MongoDB is installed ensure `mongod` is running. If it is not running then start the service. #### Downloading the API source and dependencies -Run the following command to retrieve the API and all it's dependencies. The API source will be cloned to a folder called `api` in your current directory. +Run the following command to retrieve the API and all its dependencies. The API source will be cloned to a folder called `api` in your current directory. ``` git clone https://github.com/HackIllinois/api.git ``` @@ -72,13 +72,13 @@ make run There are also `make` targets provided for building a containerized version of the API for usage in production deployments. ### Building the API Container -Building a container requires that docker and go have already been installed. The following command should be run from the root of the api repository. +Building a container requires that Docker and Go have already been installed. The following command should be run from the root of the API repository. ``` make container ``` ### Running the API Container -You can obtain all released versions and the latest version of the container from [DockerHub](https://hub.docker.com/r/hackillinois/api). The API container takes the name of the service to run as it's command arguement in the following docker run command. Ensure that the correct environment variables are set to load the configuration file and overwrite any secret configuration variables. +You can obtain all released versions and the latest version of the container from [DockerHub](https://hub.docker.com/r/hackillinois/api). The API container takes the name of the service to run as its command argument in the following `docker run` command. Ensure that the correct environment variables are set to load the configuration file and overwrite any secret configuration variables. ``` docker run -d --env-file env.config hackillinois/api:latest ``` diff --git a/documentation/docs/reference/api-writers/documentation-system.md b/documentation/docs/reference/api-writers/documentation-system.md index a8ce541e..a63a948c 100644 --- a/documentation/docs/reference/api-writers/documentation-system.md +++ b/documentation/docs/reference/api-writers/documentation-system.md @@ -1,7 +1,7 @@ # Documentation System We use [MkDocs](https://www.mkdocs.org/) for our documentation, and host at [HackIllinois API Docs](https://docs.api.hackillinois.org). -MkDocs is a Python module generates a static website, and/or a live-reloading server, from our Markdown-based documentation. It relies on a configuration file called `mkdocs.yml`, that is located the `documentation`. This configuration file can be used to specify the theme as well as menu structure of the documentation. +MkDocs is a Python module which generates a static website, and/or a live-reloading server, from our Markdown-based documentation. It relies on a configuration file called `mkdocs.yml`, that is located in the `documentation` folder. This configuration file can be used to specify the theme as well as menu structure of the documentation. ## Commands Here are the commands that can be used for interfacing with MkDocs. diff --git a/documentation/docs/reference/introduction.md b/documentation/docs/reference/introduction.md index e866f096..79635b31 100644 --- a/documentation/docs/reference/introduction.md +++ b/documentation/docs/reference/introduction.md @@ -2,13 +2,13 @@ Our API is organized as a collection of [microseverices](https://en.wikipedia.org/wiki/Microservices), behind [Arbor](https://github.com/arbor-dev/arbor), a statically configured API framework, which acts as an API Gateway. -Each microservice is responsible for doing only one set of tasks. For example, our [user service](/reference/services/user-service) is only responsible for storing and processing data for the various kinds of users our API deals with - mentors, participants, staff, etc. +Each microservice is responsible for doing only one set of tasks. For example, our [user service](/reference/services/User) is only responsible for storing and processing data for the various kinds of users our API deals with - mentors, participants, staff, etc. For authorization we use [JSON Web Tokens (JWTs)](https://jwt.io) that encode a user ID and some more information, in a system similar to [Bearer (or token-based) authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/). -When a client makes an HTTP request to `api.hackillinois.org`, it is taken through several middleware. One of them is the *Authentication* middleware, which ensures the user is authenticated. Another one is the *Identification* middleware, and puts the user ID of the requesting user in the HackIllinois-Identity header, which can be used by the individual services. The *Error* middleware allows passing of errors to the client using standard HTTP mechanisms, such as status codes, and response bodies. +When a client makes an HTTP request to `api.hackillinois.org`, it is taken through several middleware. One of them is the *Authentication* middleware, which ensures the user is authenticated. Another one is the *Identification* middleware, which puts the user ID of the requesting user in the HackIllinois-Identity header, which can then be used by the individual services. The *Error* middleware allows passing of errors to the client using standard HTTP mechanisms, such as status codes, and response bodies. -The authorized request is then forwarded to the relevant micro-service based on routes configured in the [gateway](/reference/gateway), where controllers present in each micro-service process the request, call various service funcitons, perform the action requested, and return the response, which is passed back to the user, via Arbor. +The authorized request is then forwarded to the relevant micro-service based on routes configured in the [gateway](/reference/gateway/routes/), where controllers present in each micro-service process the request, call various service functions, perform the action requested, and return the response, which is passed back to the user, via Arbor. Our persistence layer consists of a [MongoDB](https://mongodb.com) database, which has collections storing data relevant to each service. diff --git a/documentation/docs/reference/services/Authorization.md b/documentation/docs/reference/services/Authorization.md index 43ce94a5..9e4b17e8 100644 --- a/documentation/docs/reference/services/Authorization.md +++ b/documentation/docs/reference/services/Authorization.md @@ -52,7 +52,7 @@ Response format: GET /auth/roles/ ----------------------- -Gets the roles of the user with the `id` in the jwt. +Gets the roles of the current user. Response format: ```