Generic documentation

Introduction

What is?

Helper is an application that is used for helping people find any services around them in a very quick time.

<aside> 📱 Usage: imagine we are traveling abroad by car and a tire gets a flat, what a disgrace! Usually we have a spare wheel, but this time we don’t so we decide to open google and look for the closest car mechanic, maybe we are in a country where english isn’t the official language and we encounter some difficulties when we try calling and asking for some solutions to the mechanic. Here is where “Helper” help us. Helper is smart application made exactly to help us when we encounter unexpected events, it geolocalize the user and through a quick search for the service needed it gives you all the points of interest that could help you by listing their services, prices and quick contacts. We could actually call them Helpers for real! This use case is just one of many we can imagine about when we are looking for some help, we could have applied other cases of different relevance, for example the need of a haircut, or to wash the dog or even to repair something that has broken, Helper will be there to help us!

</aside>

How it works?

Who should use it?

Literally everyone.

How it is made?

Project structure

<aside> <img src="https://prod-files-secure.s3.us-west-2.amazonaws.com/97b6bdcb-5e88-4b2d-bc5b-aba94d4f08be/0d31710f-bada-4d1d-b505-aaf6043da188/web-size_1073465.png" alt="https://prod-files-secure.s3.us-west-2.amazonaws.com/97b6bdcb-5e88-4b2d-bc5b-aba94d4f08be/0d31710f-bada-4d1d-b505-aaf6043da188/web-size_1073465.png" width="40px" /> Backend

</aside>

<aside> <img src="https://prod-files-secure.s3.us-west-2.amazonaws.com/97b6bdcb-5e88-4b2d-bc5b-aba94d4f08be/8ace4e49-9641-431a-9cf1-6d7680f2da66/webpage_14380808.png" alt="https://prod-files-secure.s3.us-west-2.amazonaws.com/97b6bdcb-5e88-4b2d-bc5b-aba94d4f08be/8ace4e49-9641-431a-9cf1-6d7680f2da66/webpage_14380808.png" width="40px" /> Frontend

</aside>

<aside> <img src="https://prod-files-secure.s3.us-west-2.amazonaws.com/97b6bdcb-5e88-4b2d-bc5b-aba94d4f08be/afbc9989-d0f7-4418-9c04-dd52590dff40/interface_14549281.png" alt="https://prod-files-secure.s3.us-west-2.amazonaws.com/97b6bdcb-5e88-4b2d-bc5b-aba94d4f08be/afbc9989-d0f7-4418-9c04-dd52590dff40/interface_14549281.png" width="40px" /> Database

</aside>

<aside> <img src="https://prod-files-secure.s3.us-west-2.amazonaws.com/97b6bdcb-5e88-4b2d-bc5b-aba94d4f08be/4bff24a9-4f8d-4b3a-ac30-7b6b9d9d8ade/devops.png" alt="https://prod-files-secure.s3.us-west-2.amazonaws.com/97b6bdcb-5e88-4b2d-bc5b-aba94d4f08be/4bff24a9-4f8d-4b3a-ac30-7b6b9d9d8ade/devops.png" width="40px" /> DevOps integration

</aside>

Sketches

Credits

Conventions

The base URL to send all API requests is https://api.notion.com. HTTPS is required for all API requests.

The Notion API follows RESTful conventions when possible, with most operations performed via GET, POST, PATCH, and DELETE requests on page and database resources. Request and response bodies are encoded as JSON.

JSON CONVENTIONS

Top-level resources have an "object" property. This property can be used to determine the type of the resource (e.g. "database", "user", etc.)
Top-level resources are addressable by a UUIDv4 "id" property. You may omit dashes from the ID when making requests to the API, e.g. when copying the ID from a Notion URL.
Property names are in snake_case (not camelCase or kebab-case).
Temporal values (dates and datetimes) are encoded in ISO 8601 strings. Datetimes will include the time value (2020-08-12T02:12:33.231Z) while dates will include only the date (2020-08-12)
The Notion API does not support empty strings. To unset a string value for properties like a urlProperty value object, for example, use an explicit null instead of "".

Code samples & SDKs

Samples requests and responses are shown for each endpoint. Requests are shown using the Notion JavaScript SDK, and cURL. These samples make it easy to copy, paste, and modify as you build your integration.

Notion SDKs are open source projects that you can install to easily start building. You may also choose any other language or library that allows you to make HTTP requests.

Pagination

Endpoints that return lists of objects support cursor-based pagination requests. By default, Notion returns ten items per API call. If the number of items in a response from a support endpoint exceeds the default, then an integration can use pagination to request a specific set of the results and/or to limit the number of returned items.****

SUPPORTED ENDPOINTS

HTTP method	Endpoint
GET	List all users
GET	Retrieve block children
GET	Retrieve a comment
GET	Retrieve a page property item
POST	Query a database
POST	Search

RESPONSES

Field	Type	Description
`has_more`	`boolean`	Whether the response includes the end of the list. `false` if there are no more results. Otherwise, `true`.
`next_cursor`	`string`	A string that can be used to retrieve the next page of results by passing the value as the `start_cursor` parameter to the same endpoint.Only available when `has_more` is true.
`object`	`"list"`	The constant string `"list"`.
`results`	`array of objects`	The list, or partial list, of endpoint-specific results. Refer to a supported endpoint's individual documentation for details.
`flatMap`	`“list array of commercials”`

Request Limits

To ensure a consistent developer experience for all API users, the Notion API is rate limited and basic size limits apply to request parameters.

Rate Limits

Rate-limited requests will return a "rate_limited" error code (HTTP response status 429). The rate limit for incoming requests per integration is an average of three requests per second. Some bursts beyond the average rate are allowed.

<aside> ❗ Rate limits may change

In the future, we plan to adjust rate limits to balance for demand and reliability. We may also introduce distinct rate limits for workspaces in different pricing plans.

</aside>

Size limits

Notion limits the size of certain parameters, and the depth of children in requests. A requests that exceeds any of these limits will return "validation_error" error code (HTTP response status 400) and contain more specific details in the "message" property.

Property value type	Inner property	Size limit
Rich text object	`text.content`	2000 characters
Rich text object	`text.link.url`	2000 characters
Rich text object	`equation.expression`	1000 characters
Any array of rich text objects		100 elements

Status Codes

HTTP response codes are used to indicate general classes of success and error.

Success Code

HTTP Status Quote	Description
200	Successfully processed request.
	Succesfully registered

Error Codes

Error responses contain more detail about the error in the response body, in the "code" and "message"properties.

HTTP Status Quote	`code`	`message`
400	invalid_json	The request body could not be decoded as JSON
	invalid_request_url	This request URL is not valid.
	invalid_request	This request is not supported.
401	unauthorized	The bearer token is not valid.

Versioning

Our API versions are named for the date the version is released. For example, our latest version is 2022-06-28.

You set the version by including a Notion-Version header. Setting the Notion-Version header in required.

curl <https://api.notion.com/v1/users/01da9b00-e400-4959-91ce-af55307647e5> \\
  -H "Authorization: Bearer secret_t1CdN9S8yicG5eWLUOfhcWaOscVnFXns"
  -H "Notion-Version: 2022-06-28"

Objects

Users

Where user objects appear in the API

User objects appear in the API in nearly all objects returned by the API, including:

Block object under created_by and last_edited_by.
Page object under created_by and last_edited_by and in people property items.
Database object under created_by and last_edited_by.
Rich text object, as user mentions.
Property object when the property is a people property.

User objects will always contain object and id keys, as described below. The remaining properties may appear if the user is being rendered in a rich text or page property context, and the bot has the correct capabilities to access those properties. For more about capabilities, see the Capabilities guide and the Authorization guide.

All users

These fields are shared by all users, including people and bots. Fields marked with * are always present.

| --- | --- | --- | --- | --- |

File

File objects contain data about a file that is uploaded to Notion, or data about an external file that is linked to in Notion.

{
  "type": "file",
  "file": {
    "url": "<https://s3.us-west-2.amazonaws.com/secure.notion-static.com/7b8b0713-dbd4-4962-b38b-955b6c49a573/My_test_image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAT73L2G45EIPT3X45%2F20221024%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221024T205211Z&X-Amz-Expires=3600&X-Amz-Signature=208aa971577ff05e75e68354e8a9488697288ff3fb3879c2d599433a7625bf90&X-Amz-SignedHeaders=host&x-id=GetObject>",
    "expiry_time": "2022-10-24T22:49:22.765Z"
  }
}

Page, embed, image, video, file, pdf, and bookmark block types all contain file objects. Icon and cover page object values also contain file objects.

Each file object includes the following fields:

| --- | --- | --- | --- |

Endpoints

Endpoints (1)

Contact us

Email

[email protected] - professional email

Github

https://github.com/Giacomop19 - projects

https://www.linkedin.com/in/giacomo-pumapillo/ - resume

Generic documentation

Introduction

What is?

How it works?

Who should use it?

How it is made?

Project structure

Sketches

Credits

Conventions

Code samples & SDKs

Pagination

Request Limits

Rate Limits

Size limits

Status Codes

Success Code

Error Codes

Versioning

Objects

Users

Where user objects appear in the API

All users

File

Endpoints

Contact us

Email

Github

Linkedin