Introduction
This concept is addressed to developers who want to make use of Intershop's APIs.
Definition of API Types
There are two main types of API:
- Service API - to connect to external systems
- Customization/Extension API - to make changes within the system
Service API
This type of API is used to connect external systems. This can be the integration of an external system, e.g., a payment service, or it can be the provisioning of services like the REST commerce API used to connect the Adobe Experience Manager.
The main sub types of service API are
- Front end REST API for service provisioning
- Back end (Managed) Service API for service integration
A reference of the existing web shop REST API can be found here:
- Overview - Intershop Commerce Management REST API.
- Reference - Omni-Channel Services Toolset REST API
- Reference - Job Handling REST API (valid to 7.9)
The creation of new REST resources is described here: Overview - REST Web Service Framework.
Information about existing back end service interfaces can be found here:
- Concept - Address Check Framework, Cookbook - Address Check Framework
- Concept - Order XML Export, Cookbook - Order Export (valid to 7.8)
- Concept - Payment Framework, Cookbook - Payment (valid to 7.7)
- Concept - Inventory, Cookbook - Inventory
- Concept - Customer Segmentation Managed Service
- Concept - Captcha Framework (valid to 7.2), Cookbook - Captcha Framework 7.2
- Concept - PDF Creation (valid to 7.10), Cookbook - PDF Creation
- Concept - Business Tracking, Cookbook - Business Tracking
- Concept - Recommendation, Cookbook - Recommendation
The creation of new service interfaces for a (Managed) Service and implementation is described here: Concept - Managed Service Framework.
Additional Software Artifacts with Strong Compatibility Contracts
- XML Import/Export schemas
- Product data feed file formats
Customization/Extension API
This type of API can be used to extend and customize the functionality within the Intershop application server, like modification of existing features or adding of new features.
Internally Intershop 7 comprises 3 layers:
- Application Layer
- Business Layer
- Platform Layer
Components in every layer can provide a certain set of Java API that can be used for customization and extension. All public API is contained in Java package named capi or in sub packages of it. All other Java types are internal and must not be used.
The application layer provides additional pipeline extension points and template extension points. They are also treated as public API.
Currently Intershop 7 supports the overloading mechanism for Intershop software artifact types. Overloading seems to be convenient in the first place, but causes major migration problems on the long run. Therefore, Intershop discourages the use of the overloading mechanism now. Use extension points instead or, if not applicable, complete application cartridges must be copied to replace the original ones. See also: Applications Framework.
API Rules
| Service API (to connect to External Systems) | Customization/Extension API | |||||||
|---|---|---|---|---|---|---|---|---|
| Service Consumer (integrate other services) | Service Provider | |||||||
| (Managed) Service API | XML Import/Export | Product Data Feeds | REST API | Platform API | Business API | Application API | ||
| Stability | HIGH | HIGH | HIGH | HIGH | MEDIUM | MEDIUM | MEDIUM | |
| API Life Cycle Rules | All code that uses or implements the API must still compile and work after minor upgrades | All files that could be imported before must be importable after a minor upgrade. | All code that uses the API must still work after minor upgrades | A patch must never break the API. Deprecated artifacts can be removed after 2 minor versions. | A patch must never break the API. Deprecated artifacts can be removed after 2 minor versions. | A patch must never break the API. Deprecated extension points can be removed after 2 minor versions | ||
| Layer | Business | Business | Business | Application | Platform | Business | Application | |
| Cartridge Types | bc_* | bc_* | bc_* | app_* | pf_* | bc_* | app_* | |
| API Artifacts | Service interfaces (Java interfaces) meant to be used by the managed service framework | XML schemas used for import and export | Product data feed file formats | All REST resources in capi packages incl. HTTP verbs, response formats, etc. |  Java Types in capi packages Java Extension Points | Java Types in capi packages Java Extension Points | Java Extension Points Pipeline Extension Points Template Extension Points Application specific extension/customization mechanisms | |
| Documentation | Javadoc Confluence/ Knowledge Base for list of deleted artifacts. | Confluence/ Knowledge Base | Confluence/ Knowledge Base | Confluence/ Knowledge Base | Javadoc Extension Point Doc Confluence/ Knowledge Base for list of deleted artifacts Intershop Studio | Javadoc Business Object Extension Doc Extension Point Doc Confluence/ Knowledge Base for list of deleted artifacts Intershop Studio | Javadoc Extension Point Doc Confluence/ Knowledge Base for list of deleted artifacts Intershop Studio | |
| Migration Tools | Intershop Studio | ETL | Intershop Studio | Intershop Studio | Intershop Studio | |||
Note
Deprecated artifacts will be removed after 2 minor versions. Conditions: artifacts are marked with @deprecated <Description why it is getting removed or with what it got replaced.> and @since x.y.0.0.
At the beginning of a development cycle each development team has to ensure that no deprecated artifacts (x.y+1.0.0) are used any longer. All deprecated artifacts (x.y+2.0.0) will be removed.