From 68d146b4a692357354e25d0c0f93edf861b37e8c Mon Sep 17 00:00:00 2001 From: Dmitriy Zaporozhets Date: Thu, 6 Jun 2013 13:19:23 +0300 Subject: Improve api docs --- doc/api/deploy_keys.md | 87 +++++++++++++++++++++++++++++++ doc/api/project_snippets.md | 108 ++++++++++++++++++++++++++++++++++++++ doc/api/projects.md | 123 -------------------------------------------- doc/api/snippets.md | 108 -------------------------------------- 4 files changed, 195 insertions(+), 231 deletions(-) create mode 100644 doc/api/deploy_keys.md create mode 100644 doc/api/project_snippets.md delete mode 100644 doc/api/snippets.md (limited to 'doc/api') diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md new file mode 100644 index 00000000000..5a394094fe6 --- /dev/null +++ b/doc/api/deploy_keys.md @@ -0,0 +1,87 @@ +## Deploy Keys + +### List deploy keys + +Get a list of a project's deploy keys. + +``` +GET /projects/:id/keys +``` + +Parameters: + ++ `id` (required) - The ID of the project + +```json +[ + { + "id": 1, + "title" : "Public key" + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4 + 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4 + soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", + }, + { + "id": 3, + "title" : "Another Public key" + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4 + 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4 + soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=" + } +] +``` + + +### Single deploy key + +Get a single key. + +``` +GET /projects/:id/keys/:key_id +``` + +Parameters: + ++ `id` (required) - The ID of the project ++ `key_id` (required) - The ID of the deploy key + +```json +{ + "id": 1, + "title" : "Public key" + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4 + 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4 + soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=" +} +``` + + +### Add deploy key + +Creates a new deploy key for a project. +If deploy key already exists in another project - it will be joined to project but only if original one was is accessible by same user + +``` +POST /projects/:id/keys +``` + +Parameters: + ++ `id` (required) - The ID of the project ++ `title` (required) - New deploy key's title ++ `key` (required) - New deploy key + + +### Delete deploy key + +Delete a deploy key from a project + +``` +DELETE /projects/:id/keys/:key_id +``` + +Parameters: + ++ `id` (required) - The ID of the project ++ `key_id` (required) - The ID of the deploy key + diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md new file mode 100644 index 00000000000..04ea367d518 --- /dev/null +++ b/doc/api/project_snippets.md @@ -0,0 +1,108 @@ +## List snippets + +Get a list of project snippets. + +``` +GET /projects/:id/snippets +``` + +Parameters: + ++ `id` (required) - The ID of a project + + +## Single snippet + +Get a single project snippet. + +``` +GET /projects/:id/snippets/:snippet_id +``` + +Parameters: + ++ `id` (required) - The ID of a project ++ `snippet_id` (required) - The ID of a project's snippet + +```json +{ + "id": 1, + "title": "test", + "file_name": "add.rb", + "author": { + "id": 1, + "username": "john_smith", + "email": "john@example.com", + "name": "John Smith", + "blocked": false, + "created_at": "2012-05-23T08:00:58Z" + }, + "expires_at": null, + "updated_at": "2012-06-28T10:52:04Z", + "created_at": "2012-06-28T10:52:04Z" +} +``` + + +## Create new snippet + +Creates a new project snippet. The user must have permission to create new snippets. + +``` +POST /projects/:id/snippets +``` + +Parameters: + ++ `id` (required) - The ID of a project ++ `title` (required) - The title of a snippet ++ `file_name` (required) - The name of a snippet file ++ `lifetime` (optional) - The expiration date of a snippet ++ `code` (required) - The content of a snippet + + +## Update snippet + +Updates an existing project snippet. The user must have permission to change an existing snippet. + +``` +PUT /projects/:id/snippets/:snippet_id +``` + +Parameters: + ++ `id` (required) - The ID of a project ++ `snippet_id` (required) - The ID of a project's snippet ++ `title` (optional) - The title of a snippet ++ `file_name` (optional) - The name of a snippet file ++ `lifetime` (optional) - The expiration date of a snippet ++ `code` (optional) - The content of a snippet + + +## Delete snippet + +Deletes an existing project snippet. This is an idempotent function and deleting a non-existent +snippet still returns a `200 Ok` status code. + +``` +DELETE /projects/:id/snippets/:snippet_id +``` + +Parameters: + ++ `id` (required) - The ID of a project ++ `snippet_id` (required) - The ID of a project's snippet + + +## Snippet content + +Returns the raw project snippet as plain text. + +``` +GET /projects/:id/snippets/:snippet_id/raw +``` + +Parameters: + ++ `id` (required) - The ID of a project ++ `snippet_id` (required) - The ID of a project's snippet diff --git a/doc/api/projects.md b/doc/api/projects.md index d3d15ab4e02..7818d8071e4 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -381,126 +381,3 @@ Parameters: + `id` (required) - The ID of the project. + `branch` (required) - The name of the branch. - -### List tags - -Lists all tags of a project. - -``` -GET /projects/:id/repository/tags -``` - -Parameters: - -+ `id` (required) - The ID of the project - - -### List commits - -Lists all commits with pagination. If the optional `ref_name` name is not given the commits of -the default branch (usually master) are returned. - -``` -GET /projects/:id/repository/commits -``` - -Parameters: - -+ `id` (required) - The Id of the project -+ `ref_name` (optional) - The name of a repository branch or tag -+ `page` (optional) - The page of commits to return (`0` default) -+ `per_page` (optional) - The number of commits per page (`20` default) - -Returns values: - -+ `200 Ok` on success and a list with commits -+ `404 Not Found` if project with id or the branch with `ref_name` not found - - - -## Deploy Keys - -### List deploy keys - -Get a list of a project's deploy keys. - -``` -GET /projects/:id/keys -``` - -Parameters: - -+ `id` (required) - The ID of the project - -```json -[ - { - "id": 1, - "title" : "Public key" - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4 - 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4 - soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", - }, - { - "id": 3, - "title" : "Another Public key" - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4 - 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4 - soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=" - } -] -``` - - -### Single deploy key - -Get a single key. - -``` -GET /projects/:id/keys/:key_id -``` - -Parameters: - -+ `id` (required) - The ID of the project -+ `key_id` (required) - The ID of the deploy key - -```json -{ - "id": 1, - "title" : "Public key" - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4 - 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4 - soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=" -} -``` - - -### Add deploy key - -Creates a new deploy key for a project. - -``` -POST /projects/:id/keys -``` - -Parameters: - -+ `id` (required) - The ID of the project -+ `title` (required) - New deploy key's title -+ `key` (required) - New deploy key - - -### Delete deploy key - -Delete a deploy key from a project - -``` -DELETE /projects/:id/keys/:key_id -``` - -Parameters: - -+ `id` (required) - The ID of the project -+ `key_id` (required) - The ID of the deploy key - diff --git a/doc/api/snippets.md b/doc/api/snippets.md deleted file mode 100644 index 04ea367d518..00000000000 --- a/doc/api/snippets.md +++ /dev/null @@ -1,108 +0,0 @@ -## List snippets - -Get a list of project snippets. - -``` -GET /projects/:id/snippets -``` - -Parameters: - -+ `id` (required) - The ID of a project - - -## Single snippet - -Get a single project snippet. - -``` -GET /projects/:id/snippets/:snippet_id -``` - -Parameters: - -+ `id` (required) - The ID of a project -+ `snippet_id` (required) - The ID of a project's snippet - -```json -{ - "id": 1, - "title": "test", - "file_name": "add.rb", - "author": { - "id": 1, - "username": "john_smith", - "email": "john@example.com", - "name": "John Smith", - "blocked": false, - "created_at": "2012-05-23T08:00:58Z" - }, - "expires_at": null, - "updated_at": "2012-06-28T10:52:04Z", - "created_at": "2012-06-28T10:52:04Z" -} -``` - - -## Create new snippet - -Creates a new project snippet. The user must have permission to create new snippets. - -``` -POST /projects/:id/snippets -``` - -Parameters: - -+ `id` (required) - The ID of a project -+ `title` (required) - The title of a snippet -+ `file_name` (required) - The name of a snippet file -+ `lifetime` (optional) - The expiration date of a snippet -+ `code` (required) - The content of a snippet - - -## Update snippet - -Updates an existing project snippet. The user must have permission to change an existing snippet. - -``` -PUT /projects/:id/snippets/:snippet_id -``` - -Parameters: - -+ `id` (required) - The ID of a project -+ `snippet_id` (required) - The ID of a project's snippet -+ `title` (optional) - The title of a snippet -+ `file_name` (optional) - The name of a snippet file -+ `lifetime` (optional) - The expiration date of a snippet -+ `code` (optional) - The content of a snippet - - -## Delete snippet - -Deletes an existing project snippet. This is an idempotent function and deleting a non-existent -snippet still returns a `200 Ok` status code. - -``` -DELETE /projects/:id/snippets/:snippet_id -``` - -Parameters: - -+ `id` (required) - The ID of a project -+ `snippet_id` (required) - The ID of a project's snippet - - -## Snippet content - -Returns the raw project snippet as plain text. - -``` -GET /projects/:id/snippets/:snippet_id/raw -``` - -Parameters: - -+ `id` (required) - The ID of a project -+ `snippet_id` (required) - The ID of a project's snippet -- cgit v1.2.1