[Docs] Add guide on howto develop API (#9587)

* draft 1

* add suggestions
thanks to @bagasme @techknowlogick @davidsvantesson

* http methods

* use permalinks

* Apply suggestions from code review

Co-Authored-By: John Olheiser <42128690+jolheiser@users.noreply.github.com>
* Apply suggestions from code review

Co-Authored-By: John Olheiser <42128690+jolheiser@users.noreply.github.com>
* code format + add to INDEX

Co-authored-by: John Olheiser <42128690+jolheiser@users.noreply.github.com>
Co-authored-by: Lauris BH <lauris@nix.lv>

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a0134974ac0a0e1169048221697374d276acceb0..2172aeec243d87a1e49d109e062bd17387291fe0 100644 (file)
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -12,6 +12,7 @@
   - [Code review](#code-review)
   - [Styleguide](#styleguide)
   - [Design guideline](#design-guideline)
+  - [API v1](#api-v1)
   - [Developer Certificate of Origin (DCO)](#developer-certificate-of-origin-dco)
   - [Release Cycle](#release-cycle)
   - [Maintainers](#maintainers)
@@ -177,6 +178,43 @@ To maintain understandable code and avoid circular dependencies it is important
 - **templates:** Golang templates for generating the html output.
 - **vendor:** External code that Gitea depends on.
 
+## API v1
+
+The API is documented by [swagger](http://try.gitea.io/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 Gitea provides functionality that GitHub does not, a new endpoint can be created.  
+If information is provided by Gitea that is not provided by the GitHub API, a new field can be used that doesn't collide with any GitHub fields.
+
+Updating an existing API should 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 for future 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/c620eb5b2d0d874da68ebd734d3864c5224f71f7/routers/api/v1/repo/issue.go#L319-L327)).
+
+All JSON input types must be defined as a struct in `models/structs/`
+([example](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/modules/structs/issue.go#L76-L91))
+and referenced in
+[routers/api/v1/swagger/options.go](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/routers/api/v1/swagger/options.go).  
+They can then be used like the following:
+([example](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/routers/api/v1/repo/issue.go#L318)).
+
+All JSON responses must be defined as a struct in `models/structs/`
+([example](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/modules/structs/issue.go#L36-L68))
+and referenced in its category in `routers/api/v1/swagger/`
+([example](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/routers/api/v1/swagger/issue.go#L11-L16))  
+They can be used like the following:
+([example](https://github.com/go-gitea/gitea/blob/c620eb5b2d0d874da68ebd734d3864c5224f71f7/routers/api/v1/repo/issue.go#L277-L279))
+
+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 an object expects all fields to be optional (except ones to identify the object, which are required).
+
 
 ## Developer Certificate of Origin (DCO)