v1.6.1

en/open_api.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "Agendrix API",
     "description": "\nThis page contains a detailed description of Agendrix's public API. Below, you will find a Get Started section resuming the main steps leading you to your first API call, as well as an OAuth 2.0 section, describing the authentication process necessary in order to retrieve a mandatory access token. You can also access information about the API headers, responses and errors. Each endpoint is then described, grouped by their database model. Authorizations, parameters, responses, everything you need is there. Enjoy!\n\n# Getting Started\nThis guide describes how to make your first call to Agendrix's Public API.\n\n## Create an Application\nCreating an application will generate your development keys, for a sandbox environment where you can do any test you want, and a production environment. You can use the application for yourself or your clients.\n  - From the [Applications](./applications) section, click on the New Application button, and choose a name for your new application.\n  - You have now been redirected to your app general information. You can add a description, an icon and edit your application name as well. You can also see the approval status of your application. Your application needs to be approved before it can be used in production.\n  - You can retrieve your development and production credentials in their respective sections. You can regenerate your secrets, manage your redirect URIs and your scopes.\n\nYour Client ID and Client Secret are mandatory in order to retrieve your OAuth 2.0 tokens. Redirect URIs are as well - at least one.\n\n## Sandbox\nThe sandbox environment is used for testing. Your application does not require to be approved to use this environment. When using the sandbox, do not forget to change your calls accordingly - sandbox.agendrix.net/oauth instead of app.agendrix.com/oauth and api.sandbox.agendrix.net instead of api.agendrix.com.\n\nTo sign in to the sandbox environment, follow these steps:\n  - From the [Applications](./applications) section, click on your application.\n  - Go to the Sandbox tab.\n  - Click the Sign in to the sandbox link.\n\n## Retrieve an OAuth 2.0 access token\nYou need an access token to access Agendrix API. The simpler way to do so is through the OAuth 2.0 [Playground](./playground). There is also a detailed explanation of the process in the OAuth 2.0 section below.\n\n## Make an API call\nNow that you have an access token, you can use this token to make any call you like by adding the Authorization header to the request, as long as your credentials include the required scopes for a specific endpoint.\n\n# Resources\nThis section regroups the different downloadable Agendrix's API resources.\n\n## OAS 3\nAn Open API Specification document is a detailed, precise description of an API, from its security schemes to its endpoints. It has a lot of uses - our own [document](https://github.com/agendrix/openapi/blob/main/en/open_api.yml) generates a large part of this documentation, as well as the Postman collection. The Open API ecosystem is rich and mature and is used widely by the community. For more on OAS, click <a href='https://github.com/OAI/OpenAPI-Specification' target='_blank'>here</a>.\n\n## Examples\nWe also implemented basic <a href='https://github.com/agendrix/public-api-integration-examples' target='_blank'>examples</a> of integration with our API in javascript and ruby.\nThose examples include the complete OAuth flow as well as tokens handling and of course, making requests to the API.\n\n# OAuth 2.0\nAgendrix uses OAuth 2.0 protocol for authorization. Once you create an application, it can be used to request access and refresh tokens. The access token is\nvalid for a period of 2 hours and needs to be refreshed afterward using the refresh token. The access token can then be used to make API calls. For an interactive\ndemonstration of the process, use the OAuth 2.0 Playground.\n\n## Prepare the Authorization Request\nThe first step is to prepare the authorization request using the Client ID and one of the redirect URIs defined for the application - or the client. Scopes default to read when not specified.\n```\nhttps://app.agendrix.com/oauth/authorize?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&response_type=code&scope=read+write\n```\n\n## Redirect the User\nOnce the user is redirected to the authorization request, he needs to gives his approval sharing his data with the application, and choose the organization for which he wants to do so. The authorization request is then processed by the OAuth 2.0 server.\n\n## Handle the OAuth 2.0 Server Response\nIf the authorization request is valid, the OAuth 2.0 server sends an authorization code to the redirect URI specified in the authorization request. This code can be used to prepare the request to retrieve the access and refresh tokens.\n\n## Exchange the Authorization Code for Tokens\nThe final step is simply to exchange the authorization code received against the tokens. The Client ID, the Client Secret, the redirect URI and the grant type - which is always *authorization_code* - need to be included in the request. The OAuth 2.0 server then sends the access and refresh token to the redirect URI defined.\n```\ncurl --request POST 'https://app.agendrix.com/oauth/token' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n  \"client_id\": \"{CLIENT_ID}\",\n  \"client_secret\": \"{CLIENT_SECRET}\",\n  \"redirect_uri\": \"{REDIRECT_URI}\",\n  \"grant_type\": \"authorization_code\",\n  \"code\": \"{AUTORIZATION_CODE}\"\n}'\n```\n\n## Exchange the Refresh Token for new tokens\nThe retrieved access token will eventually expire - it has a TTL of 2 hours. Instead of going through all the authorizing process again, the refresh token can be used to request new access and refresh tokens. The grant type becomes *refresh_token* and the refresh token must be included in the request, along with the Client ID, Client Secret and redirect URI. A subset of the original access token scopes can also be included in the request.\n```\ncurl --request POST 'https://app.agendrix.com/oauth/token' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n  \"client_id\": \"{CLIENT_ID}\",\n  \"client_secret\": \"{CLIENT_SECRET}\",\n  \"redirect_uri\": \"{REDIRECT_URI}\",\n  \"grant_type\": \"refresh_token\",\n  \"refresh_token\": \"{REFRESH_TOKEN}\",\n}'\n```\n\nThe refresh tokens become invalid once used, but do not expire. You can repeat the refresh process as long as you need to.\n\n# Token's Owner Role\nThe data returned by the API will be scoped to the token's owner role. This means that if an access token was generated using an access grant of a manager, the data returned by the API will be scoped to the positions and sites managed by the user. Actions will also be limited by the owner's role. If you wish to retrieve all data related to an organization, the token used must be generated by an administrator of the organization.\n\n# Headers\nSpecific headers must be set in order to interact with the API. Some headers in the API's response also contain relevant information.\n\n## Requests\nAll requests made to the Agendrix's Public API must have two specific headers set. The first one is the Content-Type header. It must always be set to *application/json*, since it is the supported format by the API. The second one is the Authorization header, in which you must add your access token as *Bearer*. You can see an example of a classic curl request in the [Make an API Call](./documentation#section/Make-an-API-Call) section.\n\n## Responses\nAll responses from the API are in JSON; therefore, they all have the Content-Type header set to *application/json*. In the specific case the number of requests to the API is over the rate [limit](./documentation#section/Rate-Limiting), the headers RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset are added to the response headers. They respectively represent the rate limit of requests allowed, the remaining number of requests allowed - which is always 0 in that case - and the amount of seconds before the rate limit resets.\n\n# Rate Limiting\nThe API's rate limiting is currently set to 360 requests per minute. As long as the rate limiting is respected and the request is valid as well as its access token, it is processed by API.\n\n# Bulk Actions\n## Bulk size limit\nThe bulk size limit is currently set to a 1000 per request. Just as the rate limiting, as long as the size limit is respected, and the request and its access token are valid, it is processed by the API.\n\n# Make an API Call\nOnce you have the access token, making a call to Agendrix's Public API is rather straightforward. It is a classic HTTP request. All you have to do is add the required headers as well as the body or the query params - depending on the type of request -, as you can see in the example below.\n```\ncurl --request POST 'https://api.agendrix.com/v1/positions' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer {ACCESS_TOKEN}' \\\n--data-raw '{\n    \"name\": \"A position name\"\n}'\n```\n\n# Responses\nAll responses are in JSON. Responses structure vary slightly depending on the context.\n\n## Paginated Responses\nPaginated responses always contain the data and pagination fields. The data field represents the requested data returned by the API - for paginated responses, it is an array of objects. The pagination field represents the response pagination metadata. The pagination field contains the sort value, the search values, the page size, the limit on the page size, the current, next, previous, last, first and total pages, the total count of records and finally if the requested page is out of range.\n\n## Other Responses\nAll other responses always contain the data and errors fields. The data field represents once again the data returned by the API - but directly as an object this time - and will be null if there are errors. The errors field is an array of objects describing the error with a source, short message and/or long message fields. The errors field is null if the request is processed without errors.\n\n# Errors\n## Unauthorized Error - Code 401\nDifferent kind of unauthorized errors can happen while using the API:\n- Invalid token\n- Expired token\n- Revoked token\n- Unknown token\n- Unapproved application\n- Unauthorized operation (Your Agendrix user does not have the rights to perform the action)\n\n## Forbidden Error - Code 403\nWhen the token does not possess the required scope to perform the action.\n\n## Rate Limiting Error - Code 429\nWhen the rate limit of 180 requests per minute is not respected, a rate limit error is returned. The *RateLimit-Reset* header specifies how much time is left before another request can be made.\n\n## Internal Server Error - Code 500\nWhen an unexpected error occurs on the server, the API will return an internal server error.\n\n## Not Found Error - Code 404\nIt can happen for every endpoint that needs to retrieve an existing record - GET and PUT requests -, except for a bulk update.\n\n## Query Param Error - Code 400\nDifferent kind of query param errors can be triggered by the API:\n- If a required param is missing\n- If a param has the wrong format (i.e. dates)\n- If a param has the wrong value (i.e. sort or search values)\n\nIt can happen only for paginated endpoints - GET requests.\n\n## Input Params Error - Code 400\nIf a payload does not respect the schema specified in the documentation, the API will return an input params error. It can only occur for POST and PUT requests.\n\n## Path Param Error - Code 400\nIt can only happen for endpoints that require uncommon parameters in their path - i.e. the availability list of a member shown by date: `/members/{id}/availability_lists/{date}`.\n\n# Help\n## Contact us\nIf you cannot find the information you are looking for in this guide, you can contact us at the following email address: <a href='mailto:[email protected]'>[email protected]</a>.",
-    "version": "1.6.0"
+    "version": "1.6.1"
   },
   "servers": [
     {
@@ -3724,15 +3724,15 @@
           {
             "name": "search[from]",
             "in": "query",
-            "description": "The from date used for the search applied on the query.",
+            "description": "The 'from' date used for the search applied on the query. Required if 'updated_since', 'updated_until' or 'member_id' are not provided.",
             "schema": {
               "type": "string"
             }
           },
           {
             "name": "search[to]",
             "in": "query",
-            "description": "The to date used for the search applied on the query.",
+            "description": "The 'to' date used for the search applied on the query. The maximum range between 'from' and 'to' must be equal to or less than 31 days. Required if 'updated_since', 'updated_until' or 'member_id' are not provided.",
             "schema": {
               "type": "string"
             }

en/open_api.yml

@@ -166,7 +166,7 @@ info:
     # Help
     ## Contact us
     If you cannot find the information you are looking for in this guide, you can contact us at the following email address: <a href='mailto:[email protected]'>[email protected]</a>.
-  version: 1.6.0
+  version: 1.6.1
 servers:
 - url: https://api.agendrix.com/v1
 security:
@@ -2451,12 +2451,15 @@ paths:
           type: string
       - name: search[from]
         in: query
-        description: The from date used for the search applied on the query.
+        description: The 'from' date used for the search applied on the query. Required
+          if 'updated_since', 'updated_until' or 'member_id' are not provided.
         schema:
           type: string
       - name: search[to]
         in: query
-        description: The to date used for the search applied on the query.
+        description: The 'to' date used for the search applied on the query. The maximum
+          range between 'from' and 'to' must be equal to or less than 31 days. Required
+          if 'updated_since', 'updated_until' or 'member_id' are not provided.
         schema:
           type: string
       - name: search[updated_since]