0
# HTTP Services
1

2
System-level HTTP service handlers for creating web APIs and HTTP endpoints with enhanced system privileges, namespace access, and remote task execution capabilities.
3

4
## Capabilities
5

6
### AbstractSystemHttpServiceHandler
7

8
Abstract base class for system HTTP service handlers that can only be deployed in the system namespace.
9

10
```java { .api }
11
/**
12
 * Abstract class for system http service handlers. System handlers can only be used 
13
 * in applications that are deployed in the system namespace.
14
 */
15
@Beta
16
public class AbstractSystemHttpServiceHandler 
17
    extends AbstractHttpServiceHandler<SystemHttpServiceContext, SystemHttpServiceConfigurer> {
18
  
19
  /**
20
   * Creates a system table that conforms to the given table specification 
21
   * when the application is deployed.
22
   * @param tableSpecification the specification for the system table
23
   */
24
  protected void createTable(StructuredTableSpecification tableSpecification);
25
}
26
```
27

28
**Usage Example:**
29

30
```java
31
import io.cdap.cdap.api.service.http.AbstractSystemHttpServiceHandler;
32
import io.cdap.cdap.api.service.http.SystemHttpServiceConfigurer;
33
import io.cdap.cdap.api.service.http.HttpServiceRequest;
34
import io.cdap.cdap.api.service.http.HttpServiceResponder;
35
import io.cdap.cdap.spi.data.StructuredTableSpecification;
36

37
import javax.ws.rs.GET;
38
import javax.ws.rs.Path;
39
import javax.ws.rs.PathParam;
40

41
@Path("/system")
42
public class SystemApiHandler extends AbstractSystemHttpServiceHandler {
43
  
44
  @Override
45
  public void configure(SystemHttpServiceConfigurer configurer) {
46
    // Create system table for API metadata
47
    StructuredTableSpecification tableSpec = StructuredTableSpecification.builder()
48
      .withId("api-requests")
49
      .withFields(/* field definitions */)
50
      .build();
51
    createTable(tableSpec);
52
  }
53
  
54
  @GET
55
  @Path("/namespaces")
56
  public void listNamespaces(HttpServiceRequest request, HttpServiceResponder responder) {
57
    try {
58
      // Access system context capabilities
59
      List<NamespaceSummary> namespaces = getContext().listNamespaces();
60
      responder.sendJson(namespaces);
61
    } catch (Exception e) {
62
      responder.sendError(500, "Failed to list namespaces: " + e.getMessage());
63
    }
64
  }
65
}
66
```
67

68
### SystemHttpServiceHandler
69

70
Interface for system HTTP service handlers with capabilities not available to user service handlers.
71

72
```java { .api }
73
/**
74
 * A System HttpServiceHandler that exposes capabilities beyond those that 
75
 * are not available to user service handlers.
76
 */
77
@Beta
78
public interface SystemHttpServiceHandler 
79
    extends HttpServiceHandler<SystemHttpServiceContext, SystemHttpServiceConfigurer> {
80
  // Inherits all methods from HttpServiceHandler with system-specific context and configurer
81
}
82
```
83

84
### SystemHttpServiceConfigurer
85

86
System HTTP service configurer with capabilities beyond user configurers.
87

88
```java { .api }
89
/**
90
 * System HttpServiceConfigurer that provides capabilities beyond those 
91
 * available to user configurers.
92
 */
93
@Beta
94
public interface SystemHttpServiceConfigurer extends HttpServiceConfigurer, SystemTableConfigurer {
95
  // Inherits all methods from HttpServiceConfigurer and SystemTableConfigurer
96
}
97
```
98

99
### SystemHttpServiceContext
100

101
System HTTP service context with enhanced capabilities including macro evaluation, remote task execution, and namespace administration.
102

103
```java { .api }
104
/**
105
 * A System HttpServiceContext that exposes capabilities beyond those available 
106
 * to service contexts for user services.
107
 */
108
@Beta
109
public interface SystemHttpServiceContext 
110
    extends HttpServiceContext, TransactionRunner, SystemNamespaceAdmin {
111
  
112
  /**
113
   * Evaluates lookup macros and the 'secure' macro function using provided macro evaluator.
114
   * @param namespace the namespace context for macro evaluation
115
   * @param properties map of properties containing macros to evaluate
116
   * @param evaluator the macro evaluator to use
117
   * @return map with evaluated macros
118
   * @throws InvalidMacroException if macro evaluation fails
119
   */
120
  default Map<String, String> evaluateMacros(String namespace, 
121
                                           Map<String, String> properties, 
122
                                           MacroEvaluator evaluator) 
123
                                           throws InvalidMacroException;
124
  
125
  /**
126
   * Evaluates macros using provided macro evaluator with the provided parsing options.
127
   * @param namespace the namespace context for macro evaluation
128
   * @param properties map of properties containing macros to evaluate
129
   * @param evaluator the macro evaluator to use
130
   * @param options macro parsing options
131
   * @return map with evaluated macros
132
   * @throws InvalidMacroException if macro evaluation fails
133
   */
134
  Map<String, String> evaluateMacros(String namespace, 
135
                                    Map<String, String> properties, 
136
                                    MacroEvaluator evaluator, 
137
                                    MacroParserOptions options) 
138
                                    throws InvalidMacroException;
139
  
140
  /**
141
   * Gets preferences for the given namespace.
142
   * @param namespace the namespace to get preferences for
143
   * @param resolved whether to resolve macros in preference values
144
   * @return map of preference key-value pairs
145
   * @throws IOException if reading preferences fails
146
   * @throws IllegalArgumentException if namespace is invalid
147
   * @throws AccessException if access to namespace is denied
148
   */
149
  default Map<String, String> getPreferencesForNamespace(String namespace, boolean resolved) 
150
                                                        throws IOException, IllegalArgumentException, AccessException;
151
  
152
  /**
153
   * Returns ContextAccessEnforcer that can be used to enforce access for current request.
154
   * @return context access enforcer
155
   */
156
  ContextAccessEnforcer getContextAccessEnforcer();
157
  
158
  /**
159
   * Runs the task from RunnableTaskRequest remotely on a task worker.
160
   * @param runnableTaskRequest the task request to execute
161
   * @return task execution result as byte array
162
   * @throws Exception if task execution fails
163
   */
164
  byte[] runTask(RunnableTaskRequest runnableTaskRequest) throws Exception;
165
  
166
  /**
167
   * Returns boolean indicating whether remote task execution is enabled.
168
   * @return true if remote task execution is enabled
169
   */
170
  boolean isRemoteTaskEnabled();
171
}
172
```
173

174
**Usage Examples:**
175

176
```java
177
import io.cdap.cdap.api.service.http.SystemHttpServiceContext;
178
import io.cdap.cdap.api.service.worker.RunnableTaskRequest;
179
import io.cdap.cdap.api.macro.MacroEvaluator;
180

181
@Path("/system")
182
public class SystemApiHandler extends AbstractSystemHttpServiceHandler {
183
  
184
  @POST
185
  @Path("/evaluate-macros/{namespace}")
186
  public void evaluateMacros(@PathParam("namespace") String namespace,
187
                           HttpServiceRequest request, 
188
                           HttpServiceResponder responder) {
189
    try {
190
      SystemHttpServiceContext context = getContext();
191
      
192
      // Parse request body as properties map
193
      Map<String, String> properties = /* parse from request */;
194
      MacroEvaluator evaluator = /* create evaluator */;
195
      
196
      // Evaluate macros for the namespace
197
      Map<String, String> evaluated = context.evaluateMacros(namespace, properties, evaluator);
198
      responder.sendJson(evaluated);
199
    } catch (Exception e) {
200
      responder.sendError(500, "Macro evaluation failed: " + e.getMessage());
201
    }
202
  }
203
  
204
  @POST
205
  @Path("/run-task")
206
  public void runRemoteTask(HttpServiceRequest request, HttpServiceResponder responder) {
207
    try {
208
      SystemHttpServiceContext context = getContext();
209
      
210
      if (!context.isRemoteTaskEnabled()) {
211
        responder.sendError(503, "Remote task execution is disabled");
212
        return;
213
      }
214
      
215
      // Create task request
216
      RunnableTaskRequest taskRequest = RunnableTaskRequest.getBuilder("com.example.MyTask")
217
        .withParam("task-parameter")
218
        .withNamespace("default")
219
        .build();
220
      
221
      // Execute task remotely
222
      byte[] result = context.runTask(taskRequest);
223
      responder.sendBytes(result, "application/octet-stream");
224
    } catch (Exception e) {
225
      responder.sendError(500, "Task execution failed: " + e.getMessage());
226
    }
227
  }
228
  
229
  @GET
230
  @Path("/preferences/{namespace}")
231
  public void getNamespacePreferences(@PathParam("namespace") String namespace,
232
                                    HttpServiceRequest request, 
233
                                    HttpServiceResponder responder) {
234
    try {
235
      SystemHttpServiceContext context = getContext();
236
      
237
      // Get resolved preferences for namespace
238
      Map<String, String> preferences = context.getPreferencesForNamespace(namespace, true);
239
      responder.sendJson(preferences);
240
    } catch (Exception e) {
241
      responder.sendError(500, "Failed to get preferences: " + e.getMessage());
242
    }
243
  }
244
}
245
```
246

247
## Important Notes
248

249
- All system HTTP services must be deployed in the **system namespace** only
250
- System HTTP services have elevated privileges not available to user HTTP services
251
- API classes marked with `@Beta` annotation are subject to change
252
- Remote task execution must be enabled in CDAP configuration to use `runTask()` method
253
- Context access enforcer provides security controls for HTTP requests
254
- Macro evaluation supports both simple lookup macros and secure macro functions
255
- Preference resolution can include macro expansion when `resolved` parameter is true