Commit 65d86e0d authored by Robert Speicher's avatar Robert Speicher

Merge branch 'improve-grape-dsl-rules' into 'master'

Add an API styleguide

This adds a styleguide for API development. Spinned-of from https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6860#note_16922017.

[ci skip]

See merge request !6864
parents b33e04f9 11e40c0e
...@@ -8,6 +8,8 @@ ...@@ -8,6 +8,8 @@
## Styleguides ## Styleguides
- [API styleguide](api_styleguide.md) Use this styleguide if you are
contributing to the API.
- [Documentation styleguide](doc_styleguide.md) Use this styleguide if you are - [Documentation styleguide](doc_styleguide.md) Use this styleguide if you are
contributing to documentation. contributing to documentation.
- [SQL Migration Style Guide](migration_style_guide.md) for creating safe SQL migrations - [SQL Migration Style Guide](migration_style_guide.md) for creating safe SQL migrations
......
# API styleguide
This styleguide recommends best practices for API development.
## Instance variables
Please do not use instance variables, there is no need for them (we don't need
to access them as we do in Rails views), local variables are fine.
## Entities
Always use an [Entity] to present the endpoint's payload.
## Methods and parameters description
Every method must be described using the [Grape DSL](https://github.com/ruby-grape/grape#describing-methods)
(see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/api/environments.rb
for a good example):
- `desc` for the method summary. You should pass it a block for additional
details such as:
- The GitLab version when the endpoint was added
- If the endpoint is deprecated, and if so, when will it be removed
- `params` for the method params. This acts as description,
[validation, and coercion of the parameters]
A good example is as follows:
```ruby
desc 'Get all broadcast messages' do
detail 'This feature was introduced in GitLab 8.12.'
success Entities::BroadcastMessage
end
params do
optional :page, type: Integer, desc: 'Current page number'
optional :per_page, type: Integer, desc: 'Number of messages per page'
end
get do
messages = BroadcastMessage.all
present paginate(messages), with: Entities::BroadcastMessage
end
```
## Declared params
> Grape allows you to access only the parameters that have been declared by your
`params` block. It filters out the params that have been passed, but are not
allowed.
– https://github.com/ruby-grape/grape#declared
### Exclude params from parent namespaces!
> By default `declared(params) `includes parameters that were defined in all
parent namespaces.
– https://github.com/ruby-grape/grape#include-parent-namespaces
In most cases you will want to exclude params from the parent namespaces:
```ruby
declared(params, include_parent_namespaces: false)
```
### When to use `declared(params)`?
You should always use `declared(params)` when you pass the params hash as
arguments to a method call.
For instance:
```ruby
# bad
User.create(params) # imagine the user submitted `admin=1`... :)
# good
User.create(declared(params, include_parent_namespaces: false).to_h)
```
>**Note:**
`declared(params)` return a `Hashie::Mash` object, on which you will have to
call `.to_h`.
But we can use `params[key]` directly when we access single elements.
For instance:
```ruby
# good
Model.create(foo: params[:foo])
```
[Entity]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/api/entities.rb
[validation, and coercion of the parameters]: https://github.com/ruby-grape/grape#parameter-validation-and-coercion
...@@ -342,12 +342,6 @@ You can use the following fake tokens as examples. ...@@ -342,12 +342,6 @@ You can use the following fake tokens as examples.
Here is a list of must-have items. Use them in the exact order that appears Here is a list of must-have items. Use them in the exact order that appears
on this document. Further explanation is given below. on this document. Further explanation is given below.
- Every method must be described using [Grape's DSL](https://github.com/ruby-grape/grape/tree/v0.13.0#describing-methods)
(see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/api/environments.rb
for a good example):
- `desc` for the method summary (you can pass it a block for additional details)
- `params` for the method params (this acts as description **and** validation
of the params)
- Every method must have the REST API request. For example: - Every method must have the REST API request. For example:
``` ```
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment