SAP Business One Service Layer vs DI API vs UI API vs B1if vs API Gateway: which should you use?
By Zain Abbas, Kodenova · Updated
SAP Business One has five ways in for developers, and they are not interchangeable. Pick the wrong one and you end up with a desktop add-on nobody can use in the browser, or a web service that cannot do what the client does. This page compares them on the points that decide a project, all taken from SAP’s own documentation.
Which SAP Business One API should you use?
Use the Service Layer for anything outside the desktop client: portals, mobile apps, e-commerce and bank sync, scheduled jobs and Web client extensions. Use the UI API only to change screens in the Windows desktop client, with the DI API for its data. Use B1if when SAP already ships the scenario, and the API Gateway for Crystal Reports output.
What are the five interfaces?
- Service Layer: SAP calls it “a new generation of extension API” for SAP Business One data and services. It is an application server that exposes business objects over HTTP and OData (version 3 at
/b1s/v1, version 4 at/b1s/v2), with JSON payloads. - DI API (SAPbobsCOM): a COM library that gives programs the same business objects the client uses, with SAP’s validation. SAP documents it for C/C++, Visual Basic and .NET on Windows.
- UI API (SAPbouiCOM): a COM interface “connected to the running application”, meaning the desktop client. It lets an add-on add menus and forms, change standard forms and react to user events.
- B1if (integration framework for SAP Business One): a server component that runs business scenarios for integration with third-party software and mobile devices. SAP uses it for its own packages, such as mobile, dashboards, DATEV HR (Germany) and electronic documents.
- API Gateway Service: added in 10.0 FP 2105. It authenticates SAP Business One users and forwards requests to back-end services, chiefly the Reporting Service, giving one-time sign-in for Crystal Reports.
The Service Layer is not a separate business engine. SAP’s architecture page says it uses the same DI Core as the DI API and the same OBServer business logic (tax, posting and so on). That is why object and property names match the DI API, and why both enforce the same rules.
How do they compare side by side?
| Service Layer | DI API | UI API | B1if | API Gateway | |
|---|---|---|---|---|---|
| Protocol | HTTPS, OData v3/v4, JSON | COM (in-process DLL) | COM/DCOM to the running client | Scenario packages on a server | HTTPS gateway to back-end services |
| Runs where | App server on SUSE Linux or Windows; same host as the database or separate hosts | Any Windows machine with the DI API installed | On the user’s PC, inside the desktop client session | Integration server (Tomcat-based); on SQL Server it needs the DI API | SAP Business One server (ports 60010 and 60020 by default) |
| SAP HANA | Yes | Yes | Yes (same desktop client) | Yes | Yes |
| SQL Server | Yes, from 10.0 PL01 | Yes | Yes | Yes | Yes |
| Performance profile | Multi-process; scale out with several instances behind a load balancer; one HTTP round trip per call | No network hop, but no multithreading support | Bound to the user’s screen and events | Scenario and message based | Scoped to report requests |
| Sign-in / licence | Logs in as an SAP Business One user | Connects as an SAP Business One user | Shares the logged-in user’s session | Uses an SAP Business One user for DI calls | Authenticates SAP Business One users |
| Typical use | Portals, mobile apps, e-commerce, bank and EDI sync, scheduled jobs, AI tools | Desktop add-on data, Windows services, migration tools | Menus, forms, fields and validations in the desktop client | SAP-delivered or vendor scenarios | Crystal Reports output to other front ends |
| Web client | Yes: the Web client requires it, and Web client extensions call it | Not from the browser; server code only | No | Not a UI technology | Not a UI technology |
Which licence type each user needs for API, integration or Web client access is set in SAP’s licensing terms and checked by the License Service. Confirm it with your SAP partner before you size a project.
How do you decide which one to use?
- Does the change appear on a screen in the Windows desktop client? Use the UI API for the screen and the DI API, through the add-on’s shared connection, for data. See our add-on development guide.
- Does it appear in the Web client? Build a Web client extension. That means a Web client UI API extension on a supported view (10.0 FP 2405 or later) or a tile app, with data through the Service Layer. See SAP Business One Web client extensions.
- Does it run without a user, or from another system (shop, bank, portal, app, cloud function, AI agent)? Use the Service Layer.
- Do you need a Crystal Reports document as a service? Look at the API Gateway’s report service.
- Is the scenario already delivered as an integration framework package? Use B1if and configure it. For anything custom, go back to step 3.
- Do you need something the Service Layer does not do? Use the DI API on a Windows server. SAP lists these gaps: the RecordSet object (direct SQL through the API), XML import and export, and user transactions that span several calls (StartTransaction and EndTransaction).
What do real projects look like?
- Scanning items into a delivery inside SAP. Users work in the desktop client, so a UI API form captures the scans and the DI API posts the delivery, based on the sales order.
- Shopify or WooCommerce orders into SAP Business One. A small service polls the shop and creates business partners and sales orders through the Service Layer. Nothing has to be installed on user PCs.
- A customer or vendor portal. A web back end holds a Service Layer session pool and reads open orders, invoices and balances. We build these as business portals.
- An extra button on the sales order in the browser. A Web client UI API extension adds the button to the Sales Order Detail view. Its handler calls the Service Layer.
- Emailing an invoice PDF from another system. The API Gateway authenticates the request and the Reporting Service renders the Crystal layout.
- A nightly price import. A Service Layer job sends the changes in OData batch requests. Use the DI API instead only if one step must roll back across several calls.
Which pitfalls catch developers?
- New UDFs and UDTs do not appear in the Service Layer at once. SAP’s limitations page says newly created UDOs, UDFs and UDTs are not accessible until the Service Layer is restarted. Plan that restart into your deployment.
- No transactions across Service Layer calls. Each request, including an OData batch request, runs in its own transaction. A sequence of separate POSTs does not roll back as one unit.
- Lost sessions behind a load balancer. The session manager uses stickiness, so the load balancer must keep sending a client to the same node. Our Service Layer guide covers the B1SESSION and ROUTEID cookies.
- Calling the DI API from several threads. SAP states the DI API does not support multithreading. Use one connection per worker process, or move bulk work to the Service Layer.
- Field names that do not match SQL columns. The Service Layer and DI API use object and property names (
DocumentStatus,bost_Open), not table columns (DocStatus,O). Look up the table side in our SAP B1 table reference and build the request with the Service Layer request builder. - Writing to SAP tables with SQL. The posting logic lives in OBServer, behind both APIs. A direct SQL insert or update skips it, and stock, journals and approvals drift out of sync. Read with SQL if you need to, but write through an API.
- Building a desktop add-on for a company moving to the browser. UI API screens do not appear in the Web client. If users are moving to it, plan the Web client version from the start.
- B1if on SQL Server without the DI API. The administrator’s guide says the integration framework installer will not proceed if no DI API is installed. On SQL Server, it makes its calls through the DI API.
How does Kodenova build SAP Business One integrations?
We build on the Service Layer for anything that runs outside the client, and use the UI API and DI API for native desktop screens. All our work runs on both SQL Server and SAP HANA. Error codes are explained in DI API error codes, and saved queries in Service Layer SQLQueries errors.
If you are choosing an interface for a real project, see our SAP Business One API integration and custom add-on development services. You can also contact Kodenova with your SAP Business One version and what you need to connect.
Sources
- SAP Help Portal: About SAP Business One Service Layer
- SAP Help Portal: Service Layer system requirements (Linux and Windows, integrated or distributed mode)
- SAP Help Portal: Service Layer architecture overview (DI Core, OBServer, load balancer)
- SAP Help Portal: Service Layer functional limitations versus the DI API
- SAP Help Portal: Working with SAP Business One Service Layer, document history
- SAP Help Portal: Service Layer webhooks (10.0 FP 2602)
- SAP Help Portal: SAP Business One SDK, Data Interface API
- SAP Help Portal: SAP Business One SDK, User Interface API
- SAP Help Portal: SAP Business One SDK Help Center (UI API, DI API, DI Server)
- SAP Help Portal: DI API 10.0 reference, BoDataServerTypes enumeration
- SAP Help Portal: SAP Business One Administrator's Guide, 10.0 SP 2505 (Microsoft SQL Server, PDF)
- SAP Help Portal: What's New, Platform and Extensibility (API Gateway as of 10.0 FP 2105)
- SAP Help Portal: What's New, Platform and Extensibility (API Gateway CORS, OData client for Service Layer)
- SAP Help Portal: Integration framework for SAP Business One
- SAP Help Portal: Making Tax Digital setup (integration framework packages on SAP HANA)
- SAP Help Portal: Web client extensibility, UI API extensions (10.0 FP 2405)
Related services
Frequently asked questions
Is the DI API deprecated?
No. The DI API is still part of the SAP Business One 10.0 SDK, documented for .NET, C++ and Visual Basic, and it supports both SAP HANA and Microsoft SQL Server. SAP describes the Service Layer as its new generation of extension API, so new integrations that run outside the client usually start there.
Does the Service Layer work on Microsoft SQL Server?
Yes. The Service Layer started on the SAP HANA version. The Service Layer guide added support for SAP Business One 10.0 PL01 on Microsoft SQL Server in January 2020, and it runs on Windows as well as SUSE Linux. Current SQL Server installations set it up with the same setup wizard as the Web client.
Can my UI API add-on run in the SAP Business One Web client?
No. The classic UI API is a COM interface to the running Windows desktop client, so its menus, forms and events exist only there. The Web client has its own JavaScript UI API (from 10.0 FP 2405) and tile extensions. Logic that uses the DI API can still run on a server and serve both clients.
What is the SAP Business One API Gateway used for?
The API Gateway Service, available from 10.0 FP 2105, authenticates SAP Business One users and forwards requests to back-end services, mainly the Reporting Service for Crystal Reports. It gives one sign-in and one endpoint for report output. It is not a replacement for the Service Layer's business objects.
Should a new integration be built on B1if or the Service Layer?
If SAP or a vendor already delivers the scenario as an integration framework package, use B1if. For a custom connection between SAP Business One and a shop, bank, portal or app, most teams now build a small service on the Service Layer. It is plain HTTPS and JSON, and any developer can maintain it.
Which SAP Business One API is fastest?
There is no single answer. The DI API runs in process with no HTTP hop, but it does not support multithreading. The Service Layer adds an HTTP call per request but uses multiple processes and can scale out across several instances behind a load balancer. For bulk loads, measure both with your own data volume.
Ready to get started?
Tell us what you need. You get a clear technical answer, a fixed scope and a price, usually within 24 hours.