# Introduction # 👋 Welcome to OPLOG One API! # ***Standards and Usage of OPLOG OpenAPI*** (**Production** - https://api.oplog.one) (**Staging** - https://one-webapi-stg-01-dac9drerbbc8dtd3.westeurope-01.azurewebsites.net) OPLOG OpenAPI is a REST API that allows integration between OPLOG and its stakeholders. It follows some conventions which are described in our REST.md file. In addition, it is important to mention about a few topic and tools that we use in the project To be able to use OPLOG OpenAPI, clients should: 1- Have a **TenantId** 2- Be **authenticated** # TenantId Clients must have a valid TenantId to be able to use OPLOG OpenAPI. A TenantId can be claimed from: - __onboarding@oplog.io__ # Authentication Clients can use one of the following to get authenticated: __1- Static Token__ __2- Access Token__ ## 1- Static Token Static Token is an indefinite token that the clients can use in their requests in order to get authenticated. ### Get Static Token A StaticToken could be requested from: - __connect@oplog.io__ - __onboarding@oplog.io__ ▪ Add Static Token and Tenant Id to Header for each request. Sample Header: ``` GET /openapi/v1/products Host: api.oplog.one Authorization: X-Tenant-Id: cache-control: no-cache ``` ## 2- Access Token OPLOG OpenAPI is secured using the OAuth 2.0 protocol with the Auth0 identity server. A client can authenticate using the [Auth0 Machine to Machine Flow (Client Credentials Flow)](https://auth0.com/docs/flows/concepts/m2m-flow). __IMPORTANT!!!__ - Access tokens have a lifespan of 24 hours. - A client can request a maximum of 24 tokens within a 24-hour period. - It is recommended to reuse the same access token for all requests within the 24-hour window to avoid exceeding the token request limit. - Ensure that tokens are stored securely until they expire to prevent being blocked due to excessive token requests. A tenant can get ``client_Id`` and ``client_secret`` credentials after an OpenAPI integration created on Omnitro UI. Alternatively, we can do it for you. It is important to store these credentials because you are going to use them to be authenticated on OpenAPI. Here is how you can get authenticated on OpenAPI: ### Get Access Token: * Endpoint: POST https://omniservices-staging.eu.auth0.com/oauth/token * Payload: ``` { "audience": "https://omnitro.com/web", "grant_type": "client_credentials", "client_id": "", "client_secret": "" } ``` ▪ Add Access Token and Tenant Id to Header for each request. Sample Header: ``` GET /openapi/v1/products Host: api.oplog.one Authorization: Bearer X-Tenant-Id: cache-control: no-cache ``` # API Documentation Base URL: https://api.oplog.one All endpoints, their request and response models and other informations are documented via swagger. You can get any information you want from Swagger UI. You can access the Swagger UI by adding “/swagger/index.html” to the base url. For example: https://api.oplog.one/swagger/index.html. Also, you can see our [Postman Collection](https://documenter.getpostman.com/view/36563255/2sB2qdff7D) You can import this collection by clicking on the **Run in Postman** button at top right and access our API collection. **!!!For testing purposes, you can use our Staging environment --> https://one-webapi-stg-01-dac9drerbbc8dtd3.westeurope-01.azurewebsites.net/** Authentication on Swagger All of the endpoints are secured. Therefore, you will not be able to consume any endpoint if you do not authenticate. * Get an access_token * Open Swagger * Click “Authorize” button at top-right corner * Add “Bearer ” to the textbox * Click “Authorize” button at the opened box # Request and Response Models Request and response models are seperately listed in the enpoint’s documentation. You can alse find detail of example values, class definition of request model and enum values in models. # Throttling – Request Limitations All endpoints apply rate limits to the API requests that it receives. Every request is subject to throttling under the general limits that is 250 request per minute. All requests that are made after rate limits have been exceeded are throttled and an HTTP 429 Too Many Requests error is returned. # Dynamic Query Builder OPLOG OpenAPI uses DQB library on paged get endpoints, so consumers can query over objects. For the details, you can refer to [DQB on GitHub](https://github.com/oplog/DynamicQueryBuilder) and read the [documentation](https://oplog.github.io/DynamicQueryBuilder/dqb.html). *It is important to encode DQB query with url encoding and use 'dqb=' prefix!* **Filtering** Filters are List instances in the DynamicQueryOptions class. For further reading:https://oplog.github.io/DynamicQueryBuilder/dqb.html#org1ba0514 Supported filter operations: - In, - Equals, - LessThan, - Contains, - NotEqual, - EndsWith, - StartsWith, - GreaterThan, - LessThanOrEqual, - GreaterThanOrEqual, - Any, - All DQB Query: [o=Equals&p=myFirstFilterProperty&v=myFirstValue&o=Equals&p=mySecondProperty&v=mySecondValue](https://) Valid Url Example: [?dqb=o%3DEquals%26p%3DmyFirstFilterProperty%26v%3DmyFirstValue%26o%3DEquals %26p%3DmySecondProperty%26v%3DmySecondValue](https://) Real Example: https://api.oplog.one/openapi/v1/products?dqb=o%3DGreaterThan%26p%3DStockAmount%26v%3D0 #### IMPORTANT NOTE ON FILTERING DATE TIME VALUES When applying filters to date-time fields like "CreatedAt," ensure the time is converted to __UTC +0__. For instance, to filter sales orders created after 15:30 on 2023-12-27 in __Turkey time (UTC +3)__, convert this to 12:30 __UTC +0 (Turkey Time - 3 hours)__. Follow this conversion for your local time zone. The query format should look like this: DQB Query: [o=GreaterThan&p=CreatedAt&v=2023-12-27T12:30](https://) Valid Url: [?dqb=o%3DGreaterThan%26p%3DOrderCreatedAt%26v%3D2023-12-27T12%3A30](https://) Real Example: [https://api.oplog.one/api/SalesOrders.query?dqb=o%3DGreaterThan%26p%3DOrderCreatedAt%26v%3D2023-12-27T12%3A30] **Edge Case Example:** For a time like 01:30 on 2023-12-27 in __Turkey time (UTC +3)__, after converting to __UTC +0__, it becomes 22:30 on the __previous day__, __2023-12-26__. Notice the day of the date also changed. This demonstrates the importance of adjusting both the time and the date. DQB Query: [o=GreaterThan&p=CreatedAt&v=2023-12-26T22:30](https://) Valid Url: [?dqb=o%3DGreaterThan%26p%3DOrderCreatedAt%26v%3D2023-12-26T22%3A30](https://) Real Example: [https://api.oplog.one/api/SalesOrders.query?dqb=o%3DGreaterThan%26p%3DOrderCreatedAt%26v%3D2023-12-27T12%3A30] Remember, the accuracy of your query results depends on correct time zone conversion to __UTC +0__. **Sorting** Sorting is an option to DynamicQueryOptions class as a SortOption instance. For further reading: https://oplog.github.io/DynamicQueryBuilder/dqb.html#org90ad051 DQB Query: [s=myproperty,asc ](https://) Valid Url Example: [?dqb=s%3Dmyproperty%2Casc](https://) Real Example: https://api.oplog.one/openapi/v1/products?dqb=s%3DStockAmount%2Casc **Filtering, Sorting and Pagination Example** Case: Find products that are in stock ( StockAmount is greater than 0), put them in ascending order by StockAmount, and get the top 10 items: DQB Query: [offset=0&count=10&s=StockAmount,asc&o=GreaterThan&p=StockAmount&v=0](https://) Valid Url Example: [?dqb=offset%3D0%26count%3D10%26s%3DStockAmount%2Casc%26o%3DGreaterThan %26p%3DStockAmount%26v%3D0](https://) Real Example: (https://api.oplog.one/openapi/v1/products?dqb=offset%3D0%26count%3D10%26s%3DStoc kAmount%2Casc%26o%3DGreaterThan%26p%3DStockAmount%26v%3D0) ![get-started-icon](https://img.icons8.com/cotton/128/000000/launch-rocket.png)