Markdown

You should familiarize yourself with Markdown, the syntax that readme.io uses.

A good Markdown overview can be found here.

Headlines Should Be Bold

Always use the Markdown bold syntax of **wrapping text in double asterisks** to ensure that headlines are bolded.

Spacing

Keep sections spaced apart with at least one additional line break for visual clarity.

This allows you to control the spacing, like this:

Brevity

Keep sentences and paragraphs short. No walls of text - break things down into small, discrete ideas and separate with line breaks.

This keeps the content digestible and visually clean.

Tone, Formatting and Structure

Comprehensive guidelines for tone, formatting and structure can be found on Confluence.

🚧

Use Callouts

For cautionary notes or easily-overlooked functionality, use callouts to ensure clarity.

Code Fields Should Be Styled Inline

Any references to specific query parameters (e.g. campaignIds or bidValue) should employ the code comment Markdown syntax of wrapping in backticks.

Code Examples

Every code example should be prefaced with a brief description of the request and the API endpoint being used.

https://api.criteo.com/v1/my-endpoint

The endpoint should be block-quoted with three backticks and always immediately follow the brief description.

Code examples should use the publicly-available API client libraries / SDKs. Ask others if you need assistance generating code examples.

Examples should be added in as many languages as possible:

console.log('Hello world.');

print('Hello world.')

echo 'Hello world.';

Link to API Reference Frequently

Instead of describing every possible filter or optional parameter, make sure to include frequent references to relevant technical reference pages, which will be automatically be kept up to date as the Swagger documentation JSON is updated.

API Response Examples

Example requests, especially GET requests, should include an example response payload:

{
    "status": "OK",
    "data": []
}

Once a sample response has been shown on a page, there is no need to repeat the example for subsequent example requests unless there is a substantial or notable difference in response payloads for similar requests.

Guides Structure

Endpoints

{name} Attributes (NEW - table format)

* Required

{name} Attributes (DEPRECATED - see table format above)

[Example GET request] Get entity name

This endpoint retrieves all entities blablabla

Results are paginated using offset and limit query parameters; if omitted, defaults to 0 and 500, respective - see API Response

OR

Results are paginated using pageIndex and pageSize query parameters; if omitted, defaults to 0 and 25, respective - see API Response

(above can be skipped if not applicable)

https://api.criteo.com/{version}/retail-media/..../...?pageIndex={pageIndex}&pageSize={pageSize}

Sample Request

curl -X GET "https://api.criteo.com/{version}/retail-media/.../...?pageIndex=0&pageSize=25" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"

Sample Response

🔵 HTTP code 200: (can be skipped if 200 and valid response body)

{
    "data": [
        {
            "foo": "bar1"
        },
 
        // ...
 
        {
            "foo": "bar2"
        }
    ],
    "metadata": {
        "totalItemsAcrossAllPages": 15,
        "currentPageSize": 25,
        "currentPageIndex": 0,
        "totalPages": 1
    }
}

[Example POST request] Create entity name

https://api.criteo.com/{version}/retail-media/.../...

Sample Request

curl -L -X POST 'https://api.criteo.com/{version}/retail-media/.../...' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>'
  -d '{
          "foo": "bar"
      }'

Sample Response

🔵 HTTP code 204 (no body content) (required if not 200 and no response body)

{
    "foo": "bar"
}

[Example PUT request] Edit entity name

...

[Example DELETE request] Delete entity name

...

Responses