{"title":"Tips for working with APIs","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-connect-apps-tips/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-connect-apps-tips, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-connect-apps-tips","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Provides some tips about working with Business Central API.","date":"2026-09-22","meta":{"topic":"article"},"outline":[{"level":1,"title":"Tips for working with APIs","slug":"tips-for-working-with-apis","at":0,"chars":6057},{"level":2,"title":"GET","slug":"get","at":29,"chars":1247},{"level":2,"title":"Accept-Language HTTP header","slug":"accept-language-http-header","at":1276,"chars":1231},{"level":3,"title":"Example","slug":"example","at":2104,"chars":403},{"level":4,"title":"Request headers","slug":"request-headers","at":2230,"chars":96},{"level":4,"title":"Request body","slug":"request-body","at":2326,"chars":63},{"level":4,"title":"Response","slug":"response","at":2389,"chars":118},{"level":2,"title":"OData transactional $batch requests","slug":"odata-transactional-batch-requests","at":2507,"chars":892},{"level":2,"title":"Specify data access intent for API requests","slug":"specify-data-access-intent-for-api-requests","at":3399,"chars":2405},{"level":3,"title":"Possible header values","slug":"possible-header-values","at":4179,"chars":1216},{"level":3,"title":"Example","slug":"example-1","at":5395,"chars":409},{"level":4,"title":"Request headers","slug":"request-headers-1","at":5521,"chars":102},{"level":4,"title":"Request body","slug":"request-body-1","at":5623,"chars":63},{"level":4,"title":"Response","slug":"response-1","at":5686,"chars":118},{"level":2,"title":"Related information","slug":"related-information","at":5804,"chars":253}],"text":"# Tips for working with APIs\n## GET\n Call (GET) the endpoint to list all the API\n Call (GET) the endpoint with `$metadata` to list all metadata for the API\n Calling a resource API (GET) will return a list of all instances of the resource type\n Each resource is uniquely identified through an ID, see the following example:\n  ```json\n  {\n      \"@odata.context\": \"<endpoint>/$metadata#companies\",\n      \"value\": [\n          {\n              \"id\": \"a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1\",\n              \"systemVersion\": \"18453\",\n              \"name\": \"CRONUS USA, Inc.\",\n              \"displayName\": \"CRONUS USA, Inc.\",\n              \"businessProfileId\": \"\"\n          }\n      ]\n  }\n  ```\n The resource ID must be provided in the URL when trying to read or modify a resource or any of its children. The ID is provided in () after the API endpoint. For example, to GET the \"CRONUS USA, Inc.\" company details, you must call `<endpoint>/companies(a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1)/`\n All resources live in the context of a parent company, which means that the company ID must be provided in the URL for all resource API calls. For example, to GET all customers in the \"CRONUS USA, Inc.\" company, you must call `<endpoint>/companies(a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1)/customers`\n## Accept-Language HTTP header\nBy specifying `Accept-Language` in the request header, you can set a specific language for your web service response. It's recommended to use this setting, if your app is dependent on a web service response to be in a specific language. If `Accept-Language` is set, it will override default settings. This setting also controls the regional formatting settings, affecting behavior such as how date and time will be formatted.\nOne of the most common examples is showing error messages to the users in their language. To see which possible error messages to display, see ../webservices/dynamics-error-codes. Another common example is displaying reports in a specific language, see the example below for how to specify `Accept-Language`. The following example sets the language to always be `en-US`.\n### Example\n`GET businesscentralPrefix/companies({id})/salesInvoices({salesInvoiceId})/pdfDocument({salesInvoiceId})/content`\n#### Request headers\nHeader|Value\nAuthorization|Bearer {token}. Required.\nAccept-Language|en-US\n#### Request body\nDon't supply a request body for this method.\n#### Response\nIf successful, this method returns a `200 OK` response code and a report PDF file in the response body.\n## OData transactional $batch requests\n> APPLIES TO: Business Central 2020 release wave 2 (version 17.1) and later\nIt's possible to specify that all inner requests in a certain OData $batch request are processed in a transactional way. If one of the inner requests fails after another request (or requests) has committed changes, all changes within a batch will be reverted as if the batch request never happened. Transactional $batch requests are useful in scenarios where a single business operation spans multiple requests, because they prevent adverse effects if parts of the operation fail. Also, they can improve performance by reducing the number of requests the client needs to do when errors occur.\nTo enable transactional batch behavior, include the `Isolation: snapshot` header with the $batch request.\nSee Using OData Transactional $batch Requests<../webservices/use-odata-batch>\n## Specify data access intent for API requests\nBy specifying HTTP request header `Data-Access-Intent`, it's possible to override data access intent of the API page or query that has been defined with properties/devenv-dataaccessintent-property.\n> NOTE\n> Setting the DataAccessIntent property to ReadOnly doesn't guarantee that your data access will be running on the secondary replica. It's merely stating that the code only requires read ability, so a read-only connection can be used.\n> For example, the property doesn't apply to queries running at arbitrary times during normal AL execution (that is, the server doesn't change to ReadOnly mode in the middle of a transaction). So for queries, the property only fully applies when they're exposed as an API/OData feed directly.\n### Possible header values\nValue|Description\nReadOnly|Intent to access records, but not to modify them. The page or query reads data from a replica of the database (if available), reducing the load on the primary database, but prevents modifications to the database records.\nReadWrite|Intent to access and modify records.\nWhen request header is specified, the value of the DataAccessIntent property defined on the object, if any, is ignored. Overrides that are specified on the page 9880 Database Access Intent List take higher precedence than the value in the request header.\nModification requests (like POST, PATCH, PUT, or DELETE) only support ReadWrite as a value for data access intent. If you try to specify `Data-Access-Intent: ReadOnly` for such requests, the API returns an error.\n> NOTE\n> In Business Central online, the methods advertised by an OPTIONS request for the same API endpoint can depend on the request's `Data-Access-Intent` header. For example, ReadOnly can produce an Allow header that excludes modification methods that are advertised when the header is omitted or set to ReadWrite. Include this header when comparing endpoint capabilities or troubleshooting unexpected method availability.\n### Example\n`GET businesscentralPrefix/companies({id})/salesInvoices({salesInvoiceId})/pdfDocument({salesInvoiceId})/content`\n#### Request headers\nHeader|Value\nAuthorization|Bearer {token}. Required.\nData-Access-Intent|ReadOnly\n#### Request body\nDon't supply a request body for this method.\n#### Response\nIf successful, this method returns a `200 OK` response code and a report PDF file in the response body.\n## Related information\nUsing filtering With APIs<devenv-connect-apps-filtering>\nAPI performance<../webservices/web-service-performance>\nPerformance articles For developers<../performance/performance-developer>\nproperties/devenv-dataaccessintent-property"}