http methods

CONTRIBUTING.md

@@ -98,7 +98,7 @@ the same change, be it a bugfix or a feature addition.
 
 The `vendor/` update needs to be justified as part of the PR description,
 and must be verified by the reviewers and/or merger to always reference
-an existsing upstream commit.
+an existing upstream commit.
 
 You can find more information on how to get started with it on the [Modules Wiki](https://github.com/golang/go/wiki/Modules).
 
@@ -182,15 +182,22 @@ To maintain understandable code and avoid circular dependencies it is important
 The API is documented by [swagger](http://gitea.com/api/swagger) and is based on [GitHub API v3](https://developer.github.com/v3/).
 Thus, Gitea´s API should use the same endpoints and fields as GitHub´s API as far as possible, unless there are good reasons to deviate. If GitHub doesn't provide...
 
+Updating an existing API does not remove existing fields unless there is a really good reason to do so.
+The same applies to status responses, if you notice a problem, feel free to leave a comment in the code if there is a refactoring to APIv2 (which is currently not planned).
+
 All expected results (errors, success, fail messages) should be documented ([example](https://github.com/go-gitea/gitea/blob/master/routers/api/v1/repo/issue.go#L319-L327)).
 
 All JSON input types must be defined as struct in `models/structs/` ([example](https://github.com/go-gitea/gitea/blob/master/modules/structs/issue.go#L76-L91)) and referenced in [routers/api/v1/swagger/options.go](https://github.com/go-gitea/gitea/blob/master/routers/api/v1/swagger/options.go), they can be used then as following: ([example](https://github.com/go-gitea/gitea/blob/master/routers/api/v1/repo/issue.go#L318)).
 
 All JSON responses must be defined as struct in `models/structs/` ([example](https://github.com/go-gitea/gitea/blob/master/modules/structs/issue.go#L36-L68)) and referenced in its category in `routers/api/v1/swagger/` ([example](https://github.com/go-gitea/gitea/blob/master/routers/api/v1/swagger/issue.go#L11-L16)), they can be used as following: ([example](https://github.com/go-gitea/gitea/blob/master/routers/api/v1/repo/issue.go#L277-L279))
 
- * GET endpoints return status `OK (200)`,
- * POST endpoints return status `Created (201)` and
- * DELETE endpoints return status `No Content (204)`
+In general, http methods are chosen as follows:
+ * **GET** endpoints return requested object and status **OK (200)**
+ * **DELETE** endpoints return status **No Content (204)**
+ * **POST** endpoints return status **Created (201)**, used to **create** new objects (e.g. a User)
+ * **PUT** endpoints return status **No Content (204)**, used to **add/assign** existing Obejcts (e.g. User) to something (e.g. Org-Team)
+ * **PATCH** endpoints return changed object and status **OK (200)**, used to **edit/change** an existing object
+
 
 An endpoint which changes/edits a object expects all fields to be optional (except ones to identify the object, which is required).