From 2ddaf0038710d057e96f8211036399aa65d3ddb4 Mon Sep 17 00:00:00 2001 From: Felix Gilcher Date: Mon, 28 Jan 2013 14:49:27 +0100 Subject: [PATCH 1/3] Added documentation for passing the token as header The documentation was unclear about how to pass the api private token as header. Updated the doc to include the nessesary information bits and added an example using the curl command line client. --- doc/api/README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/api/README.md b/doc/api/README.md index 477429c9fa0..881d4ab638f 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -1,6 +1,6 @@ # GitLab API -All API requests require authentication. You need to pass a `private_token` parameter by url or header. You can find or reset your private token in your profile. +All API requests require authentication. You need to pass a `private_token` parameter by url or header. If passed as header, the header name must be "PRIVATE-TOKEN" (capital and with dash instead of underscore). You can find or reset your private token in your profile. If no, or an invalid, `private_token` is provided then an error message will be returned with status code 401: @@ -18,6 +18,13 @@ Example of a valid API request: GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U ``` +Example for a valid API request using curl and authentication via header: + +``` +curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://example.com/api/v3/projects" +``` + + The API uses JSON to serialize data. You don't need to specify `.json` at the end of API URL. #### Pagination From a90d5c21b55584572ff22d7a3affd84cd19d38d2 Mon Sep 17 00:00:00 2001 From: Felix Gilcher Date: Mon, 28 Jan 2013 16:46:58 +0100 Subject: [PATCH 2/3] describe the project access level the documentation mentions access_level as required parameter, but fails to list accepted values. --- doc/api/projects.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/api/projects.md b/doc/api/projects.md index 411286750f8..e8730173c0a 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -107,6 +107,18 @@ Parameters: Will return created project with status `201 Created` on success, or `404 Not found` on fail. +## Project access levels + +The project access levels are defined in the `user_project` class. Currently, 4 +levels are recoginized: + +``` + GUEST = 10 + REPORTER = 20 + DEVELOPER = 30 + MASTER = 40 +``` + ## List project team members Get a list of project team members. From e76215a395bb814972c1385ce815b2da2a6e3402 Mon Sep 17 00:00:00 2001 From: Felix Gilcher Date: Mon, 28 Jan 2013 23:51:45 +0100 Subject: [PATCH 3/3] Update docs to reflect that project names are allowed as ID The API accepts project names in all places where project IDs are expected. Updated the docs to reflect that. --- doc/api/projects.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/doc/api/projects.md b/doc/api/projects.md index e8730173c0a..64d79a0d51b 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -53,7 +53,8 @@ GET /projects ## Single project -Get a specific project, identified by project ID, which is owned by the authentication user. +Get a specific project, identified by project ID or NAME, which is owned by the authentication user. +Currently namespaced projects cannot retrieved by name. ``` GET /projects/:id @@ -61,7 +62,7 @@ GET /projects/:id Parameters: -+ `id` (required) - The ID of a project ++ `id` (required) - The ID or NAME of a project ```json { @@ -129,7 +130,7 @@ GET /projects/:id/members Parameters: -+ `id` (required) - The ID of a project ++ `id` (required) - The ID or NAME of a project + `query` - Query string ## Get project team member @@ -142,7 +143,7 @@ GET /projects/:id/members/:user_id Parameters: -+ `id` (required) - The ID of a project ++ `id` (required) - The ID or NAME of a project + `user_id` (required) - The ID of a user ```json @@ -168,7 +169,7 @@ POST /projects/:id/members Parameters: -+ `id` (required) - The ID of a project ++ `id` (required) - The ID or NAME of a project + `user_id` (required) - The ID of a user to add + `access_level` (required) - Project access level @@ -184,7 +185,7 @@ PUT /projects/:id/members/:user_id Parameters: -+ `id` (required) - The ID of a project ++ `id` (required) - The ID or NAME of a project + `user_id` (required) - The ID of a team member + `access_level` (required) - Project access level @@ -200,7 +201,7 @@ DELETE /projects/:id/members/:user_id Parameters: -+ `id` (required) - The ID of a project ++ `id` (required) - The ID or NAME of a project + `user_id` (required) - The ID of a team member Status code `200` will be returned on success. @@ -215,7 +216,7 @@ GET /projects/:id/hooks Parameters: -+ `id` (required) - The ID of a project ++ `id` (required) - The ID or NAME of a project Will return hooks with status `200 OK` on success, or `404 Not found` on fail. @@ -229,7 +230,7 @@ GET /projects/:id/hooks/:hook_id Parameters: -+ `id` (required) - The ID of a project ++ `id` (required) - The ID or NAME of a project + `hook_id` (required) - The ID of a project hook Will return hook with status `200 OK` on success, or `404 Not found` on fail. @@ -244,7 +245,7 @@ POST /projects/:id/hooks Parameters: -+ `id` (required) - The ID of a project ++ `id` (required) - The ID or NAME of a project + `url` (required) - The hook URL Will return status `201 Created` on success, or `404 Not found` on fail. @@ -259,7 +260,7 @@ PUT /projects/:id/hooks/:hook_id Parameters: -+ `id` (required) - The ID of a project ++ `id` (required) - The ID or NAME of a project + `hook_id` (required) - The ID of a project hook + `url` (required) - The hook URL @@ -276,7 +277,7 @@ DELETE /projects/:id/hooks Parameters: -+ `id` (required) - The ID of a project ++ `id` (required) - The ID or NAME of a project + `hook_id` (required) - The ID of hook to delete Will return status `200 OK` on success, or `404 Not found` on fail.