---
myst:
  html_meta:
    "description": "Contribute to plone.restapi"
    "property=og:description": "Contribute to plone.restapi"
    "property=og:title": "Contribute to plone.restapi"
    "keywords": "Plone, plone.restapi, REST, API, contribute, documentation"
---

# Contribute to `plone.restapi`

This section describes how to contribute to the `plone.restapi` project.
It extends {doc}`plone:contributing/index`.


## Prerequisites

Prepare your system by installing {ref}`plone:plone-prerequisites-label`.


## Set up development environment

We use GNU `make` when developing `plone.restapi`.
To install this package, its dependencies, and its documentation, code formatting, and testing tools, run the following command in the root of the project.

```shell
make install
```

To see all the Makefile targets and help, use the following command.

```shell
make help
```


## Start Plone

```shell
make start
```


## Run frontend tests against the acceptance server

To test a frontend against your local `plone.restapi` checkout, install the development environment with `make install`, then start the acceptance server.
Use Plone 6 with `plone.app.robotframework` 2 or later for this server.

```shell
make acceptance-backend-start
```

Wait for `Started Zope robot server`, then configure your frontend tests to use `http://localhost:55001/plone` as their API URL.
The server uses the REST API Dexterity test fixture and a single WSGI worker thread.
Authenticate as `admin` with the password `secret` to manage the test site.

To check that the API responds, run the following command in another terminal.

```shell
curl --fail --user admin:secret --header 'Accept: application/json' \
  http://localhost:55001/plone/@types
```

Stop the server with {kbd}`Control+C` when you finish.
Restart it to recreate the site and discard all changes.


## Generate documentation examples

This documentation includes examples of requests and responses, using each of http, curl, httpie, and python-requests.
These examples are generated by the documentation tests in `test_documentation.py`.
To generate a new example, add a new test case to `test_documentation.py`, for example `test_documentation_search_fullobjects`, and run the test.

```shell
.venv/bin/zope-testrunner --test-path=src -t test_documentation_search_fullobjects
```

The above command also generates the request and the response files in `tests/http-examples/`.
Include them in the documentation using MyST syntax.

````markdown
```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../src/plone/restapi/tests/http-examples/search_fullobjects.req

..  literalinclude:: ../../src/plone/restapi/tests/http-examples/search_fullobjects.resp
    :language: http
```
````

Build the documentation locally to test the rendering.

```shell
make docs-livehtml
```

Add and commit the generated files in `src/plone/restapi/tests/http-examples/`.


## Documentation checks

Run a link checker on documentation.

```shell
make docs-linkcheckbroken
```

Run a spelling, grammar, and style checker on documentation.

```shell
make docs-vale
```


## Conventions

```{toctree}
:maxdepth: 2

conventions
```

## Code formatting and testing

All changes must pass code formatting and tests.
Run these checks locally before creating a pull request.

Use the following command to automatically format the code with [Black](https://black.readthedocs.io/en/stable/index.html).

```shell
make check
```

Use the following command to run tests.

```shell
make test
```