Skip to content

Snippets API doc fixes: content->code; visibility is required

Nikolay Samokhvalov requested to merge nik-api-snippets-fix into master

This change fixes the description of Snippets API.

I have noticed that there are two inconsistencies between the documentation and API currently deployed on GitLab.com:

  1. Documentation claims that content fields is called content, while API says that it's code.
  2. visibility field is marked as not required, while it is required in fact.

Here is an attempt to create a new snippet using API, starting from an empty request, adding required items one by one:

$ curl --header "Private-Token: XXX" --request POST --header "Content-Type: application/json" -d @- https://gitlab.com/api/v4/projects/10031681/snippets <<CDATA
> {}
> CDATA
{"error":"title is missing, file_name is missing, code is missing, code is empty, visibility is missing, visibility does not have a valid value"}

$ curl --header "Private-Token: XXX" --request POST --header "Content-Type: application/json" -d @- https://gitlab.com/api/v4/projects/10031681/snippets <<CDATA
> {"title": "test"}
> CDATA
{"error":"file_name is missing, code is missing, code is empty, visibility is missing, visibility does not have a valid value"}

$ curl --header "Private-Token: XXX" --request POST --header "Content-Type: application/json" -d @- https://gitlab.com/api/v4/projects/10031681/snippets <<CDATA
> {"title": "test", "file_name": "1.md"}
> CDATA
{"error":"code is missing, code is empty, visibility is missing, visibility does not have a valid value"}

$ curl --header "Private-Token: XXX" --request POST --header "Content-Type: application/json" -d @- https://gitlab.com/api/v4/projects/10031681/snippets <<CDATA
> {"title": "test", "file_name": "1.md", "code": "zz"}
> CDATA
{"error":"visibility is missing, visibility does not have a valid value"}

$ curl --header "Private-Token: XXX" --request POST --header "Content-Type: application/json" -d @- https://gitlab.com/api/v4/projects/10031681/snippets <<CDATA
> {"title": "test", "file_name": "1.md", "code": "zz", "visibility": "public"}
> CDATA
{"id":1859212,"title":"test","file_name":"1.md","description":null,"visibility":"public","author":{"id":1906296,"name":"Nikolay Samokhvalov","username":"NikolayS","state":"active","avatar_url":"https://assets.gitlab-static.net/uploads/-/system/user/avatar/1906296/avatar.png","web_url":"https://gitlab.com/NikolayS"},"updated_at":"2019-05-22T00:37:31.093Z","created_at":"2019-05-22T00:37:31.093Z","project_id":10031681,"web_url":"https://gitlab.com/NikolayS/test/snippets/1859212"}

From here, it's obvious that:

  • content field is called code, not content as the documentation states;
  • visibility is a required field.

This MR adjusts the documentation, in the sections related to creation and updating of snippets.

The corresponding sections in documentation:

Edited by Nikolay Samokhvalov

Merge request reports