ABAP OO REST Service Framework (S/4HANA)

1. Objective

Design and implement a reusable REST service framework in ABAP OO for S/4HANA systems that standardizes the development of HTTP-based APIs, ensuring:

• Consistency across services
• Clean separation of concerns
• Extensibility and maintainability
• Compatibility with modern ABAP (7.50+ / S/4HANA)

The framework should complement SAP technologies (e.g., SAP Gateway, RAP) and be usable in custom REST endpoints (ICF-based or handler classes).

Naming Conventions

All objects must follow the SAP Z-namespace and Clean ABAP conventions below.

Object Naming

Object Type	Pattern	Example
Global class	ZCL_REST_<NAME>	ZCL_REST_DISPATCHER
Abstract base class	ZCL_REST_<NAME>	ZCL_REST_CONTROLLER
Interface	ZIF_REST_<NAME>	ZIF_REST_CONTROLLER
Exception class	ZCX_REST_<NAME>	ZCX_REST_ERROR, ZCX_REST_NOT_FOUND
Type/structure	ZTS_REST_<NAME>	ZTS_REST_REQUEST, ZTS_REST_RESPONSE
Table type	ZTT_REST_<NAME>	ZTT_REST_HEADERS

Method Naming

• Uppercase, verb-first, underscore-separated.
• Examples: HANDLE_GET, HANDLE_POST, DISPATCH_REQUEST, BUILD_RESPONSE, SET_STATUS.

Variable Naming (Clean ABAP)

Follow standard ABAP prefix conventions:

Scope	Prefix	Example
Local variable (scalar)	lv_	lv_body, lv_status
Local structure	ls_	ls_request, ls_response
Local table	lt_	lt_params, lt_headers
Instance attribute	mv_ / ms_ / mt_	mv_version, mt_routes
Parameter (importing)	iv_ / is_ / it_	iv_path, is_request
Parameter (returning/exporting)	rv_ / rs_ / rt_	rs_response, rv_status

ICF Service Path

/sap/bc/z_rest/api/v<version>/<resource>

Example: /sap/bc/z_rest/api/v1/orders

Package

Use you local package $TMP as the development package for all objects created in this lab.

---

2. Scope

In Scope

• HTTP request handling
• Routing and dispatching
• Controller abstraction
• Request/response encapsulation
• JSON serialization/deserialization
• Error handling (mapped to HTTP responses)
• Logging hooks
• Versioning support

Out of Scope

• Full SAP Gateway replacement
• RAP BO implementation
• Advanced OAuth/security frameworks (basic hooks only)

---

3. Architecture Overview

HTTP Entry Point (ICF / Handler)
        ↓
REST Dispatcher
        ↓
Controller Layer
        ↓
Service Layer (Business Logic)
        ↓
DTO / Model Objects

---

4. Functional Requirements

4.1 Request Handling

The framework must:

• Accept incoming HTTP requests via an entry class
• Extract:
  • HTTP method (GET, POST, PUT, DELETE)
  • URI path
  • Headers
  • Query parameters
  • Request body

---

4.2 Routing & Dispatching

Implement a central dispatcher responsible for:

• Mapping requests to controllers
• Supporting URI patterns:
  • /api/v1/orders
  • /api/v1/orders/{id}
• Resolving:
  • HTTP method
  • API version
  • Resource path

---

4.3 Controller Abstraction

Provide an abstract base controller with predefined methods:

• HANDLE_GET
• HANDLE_POST
• HANDLE_PUT
• HANDLE_DELETE

Controllers must:

• Process business requests
• Return structured responses
• Avoid direct database access (delegate to services)

---

4.4 Request and Response Model

Request Object

Encapsulate:

• HTTP method
• Path and path parameters
• Query parameters
• Headers
• Body (raw + parsed JSON)

Response Object

Encapsate:

• HTTP status code
• Headers
• Response payload (JSON)

---

4.5 JSON Processing

The framework must:

• Support JSON → ABAP structure deserialization
• Support ABAP structure → JSON serialization
• Use standard S/4HANA classes:
  • /UI2/CL_JSON (preferred)

---

4.6 Error Handling

Implement a structured exception model:

Base Exception

• ZCX_REST_ERROR

Derived Exceptions

• Not found → HTTP 404
• Validation error → HTTP 400
• Internal error → HTTP 500

The framework must:

• Catch exceptions centrally
• Convert them into HTTP responses
• Ensure no unhandled dumps reach the client

---

4.7 Service Layer

• Business logic must reside in dedicated service classes
• Services must:
  • Be independent of HTTP
  • Be reusable in other contexts (e.g., reports, RAP)

---

4.8 Versioning

Support API versioning via URI:

/api/v1/...
/api/v2/...

Dispatcher must:

• Route based on version
• Allow multiple versions to coexist

---

4.9 Logging (Hook)

Provide a logging mechanism:

• Interface-based (pluggable)
• Log:
  • Request metadata
  • Errors
  • Execution time

---

5. Non-Functional Requirements

5.1 Performance

• Minimize serialization overhead
• Avoid unnecessary copying of large payloads

5.2 Maintainability

• Clear separation of layers
• Consistent naming conventions
• Reusable components

5.3 Extensibility

• Easy addition of new controllers
• Plug-in support for:
  • Authentication
  • Logging
  • Routing rules

5.4 Testability

• Support ABAP Unit
• Mockable service layer
• Controllers testable independently

---

6. Technical Requirements (S/4HANA)

• Use modern ABAP syntax:
  • Inline declarations (DATA(...))
  • Constructor expressions (NEW)
• Use standard classes:
  • /UI2/CL_JSON
• Follow Clean ABAP guidelines
• Avoid obsolete constructs
• Compatible with S/4HANA ABAP stack

---

7. Example Use Case

Scenario

Retrieve an order by ID

Request

GET /api/v1/orders/123

Flow

1. HTTP request received
2. Dispatcher resolves:
   • Version: v1
   • Resource: orders
   • ID: 123
3. Controller method HANDLE_GET is invoked
4. Service retrieves order data
5. Response object created
6. JSON returned with HTTP 200

---

8. Deliverables

The implementation must include:

• Core framework classes:
  • Dispatcher
  • Base controller
  • Request/response objects
• Example implementation:
  • Order controller
  • Order service
• Exception hierarchy
• Sample routing configuration
• Documentation:
  • How to create new endpoints
  • How to extend the framework

---

9. Acceptance Criteria

The framework is considered complete when:

• A developer can create a new API endpoint with minimal boilerplate
• Requests are correctly routed and handled
• Errors are consistently mapped to HTTP responses
• JSON input/output works reliably
• Code follows modern S/4 ABAP standards

---

10. Optional Enhancements

• Authentication interface (Basic / JWT hook)
• Middleware/interceptor pipeline
• Request validation layer
• Rate limiting hook
• Integration with SAP Application Log (SLG1)