2 * Copyright (c) 2023 PANTHEON.tech, s.r.o. and others. All rights reserved.
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Public License v1.0 which accompanies this distribution,
6 * and is available at http://www.eclipse.org/legal/epl-v10.html
8 package org.opendaylight.restconf.server.api;
12 import org.eclipse.jdt.annotation.NonNullByDefault;
13 import org.eclipse.jdt.annotation.Nullable;
14 import org.opendaylight.restconf.api.ApiPath;
15 import org.opendaylight.restconf.common.errors.RestconfFuture;
16 import org.opendaylight.restconf.common.patch.PatchStatusContext;
17 import org.opendaylight.restconf.nb.rfc8040.ReadDataParams;
18 import org.opendaylight.restconf.nb.rfc8040.databind.ChildBody;
19 import org.opendaylight.restconf.nb.rfc8040.databind.DataPostBody;
20 import org.opendaylight.restconf.nb.rfc8040.databind.OperationInputBody;
21 import org.opendaylight.restconf.nb.rfc8040.databind.PatchBody;
22 import org.opendaylight.restconf.nb.rfc8040.databind.ResourceBody;
23 import org.opendaylight.restconf.nb.rfc8040.legacy.NormalizedNodePayload;
24 import org.opendaylight.restconf.server.api.DataPostResult.CreateResource;
25 import org.opendaylight.restconf.server.spi.OperationOutput;
26 import org.opendaylight.yangtools.yang.common.Empty;
29 * An implementation of a RESTCONF server, implementing the
30 * <a href="https://www.rfc-editor.org/rfc/rfc8040#section-3.3">RESTCONF API Resource</a>.
33 public interface RestconfServer {
35 * Delete a data resource.
37 * @param identifier resource identifier
38 * @return A {@link RestconfFuture} of the operation
40 @SuppressWarnings("checkstyle:abbreviationAsWordInName")
41 RestconfFuture<Empty> dataDELETE(String identifier);
44 * Return the content of the datastore.
46 * @param readParams {@link ReadDataParams} for this request
47 * @return A {@link RestconfFuture} of the {@link NormalizedNodePayload} content
49 RestconfFuture<NormalizedNodePayload> dataGET(ReadDataParams readParams);
52 * Return the content of a data resource.
54 * @param identifier resource identifier
55 * @param readParams {@link ReadDataParams} for this request
56 * @return A {@link RestconfFuture} of the {@link NormalizedNodePayload} content
58 RestconfFuture<NormalizedNodePayload> dataGET(String identifier, ReadDataParams readParams);
61 * Partially modify the target data resource, as defined in
62 * <a href="https://www.rfc-editor.org/rfc/rfc8040#section-4.6.1">RFC8040, section 4.6.1</a>.
64 * @param body data node for put to config DS
65 * @return A {@link RestconfFuture} of the operation
67 RestconfFuture<Empty> dataPATCH(ResourceBody body);
70 * Partially modify the target data resource, as defined in
71 * <a href="https://www.rfc-editor.org/rfc/rfc8040#section-4.6.1">RFC8040, section 4.6.1</a>.
73 * @param identifier resource identifier
74 * @param body data node for put to config DS
75 * @return A {@link RestconfFuture} of the operation
77 RestconfFuture<Empty> dataPATCH(String identifier, ResourceBody body);
80 * Ordered list of edits that are applied to the datastore by the server, as defined in
81 * <a href="https://www.rfc-editor.org/rfc/rfc8072#section-2">RFC8072, section 2</a>.
83 * @param body YANG Patch body
84 * @return A {@link RestconfFuture} of the {@link PatchStatusContext} content
86 RestconfFuture<PatchStatusContext> dataPATCH(PatchBody body);
89 * Ordered list of edits that are applied to the datastore by the server, as defined in
90 * <a href="https://www.rfc-editor.org/rfc/rfc8072#section-2">RFC8072, section 2</a>.
92 * @param identifier path to target
93 * @param body YANG Patch body
94 * @return A {@link RestconfFuture} of the {@link PatchStatusContext} content
96 RestconfFuture<PatchStatusContext> dataPATCH(String identifier, PatchBody body);
98 RestconfFuture<CreateResource> dataPOST(ChildBody body, Map<String, String> queryParameters);
100 RestconfFuture<? extends DataPostResult> dataPOST(String identifier, DataPostBody body,
101 Map<String, String> queryParameters);
104 * Replace the data store.
106 * @param body data node for put to config DS
107 * @param queryParameters Query parameters
108 * @return A {@link RestconfFuture} completing with {@link DataPutResult}
110 RestconfFuture<DataPutResult> dataPUT(ResourceBody body, Map<String, String> queryParameters);
113 * Create or replace a data store resource.
115 * @param identifier resource identifier
116 * @param body data node for put to config DS
117 * @param queryParameters Query parameters
118 * @return A {@link RestconfFuture} completing with {@link DataPutResult}
120 RestconfFuture<DataPutResult> dataPUT(String identifier, ResourceBody body, Map<String, String> queryParameters);
123 * Return the set of supported RPCs supported by {@link #operationsPOST(URI, String, OperationInputBody)}.
125 * @return An {@link OperationsGetResult}
127 OperationsGetResult operationsGET();
130 * Return the details about a particular operation supported by
131 * {@link #operationsPOST(URI, String, OperationInputBody)}, as expressed in the
132 * <a href="https://www.rfc-editor.org/rfc/rfc8040#page-84>RFC8040<a> {@code container operations} statement.
134 * @param operation An operation
135 * @return An {@link OperationsContent}, or {@code null} if {@code operation} does not point to an {@code rpc}
137 // FIXME: 'operation' should really be an ApiIdentifier with non-null module, but we also support ang-ext:mount,
138 // and hence it is a path right now
139 // FIXME: use ApiPath instead of String
140 @Nullable OperationsGetResult operationsGET(String operation);
143 * Invoke an RPC operation, as defined in
144 * <a href="https://www.rfc-editor.org/rfc/rfc8040#section-3.6">RFC8040 Operation Resource</a>.
146 * @param restconfURI Base URI of the request
147 * @param operation {@code <operation>} path, really an {@link ApiPath} to an {@code rpc}
148 * @param body RPC operation
149 * @return A {@link RestconfFuture} of the {@link OperationOutput operation result}
151 // FIXME: 'operation' should really be an ApiIdentifier with non-null module, but we also support ang-ext:mount,
152 // and hence it is a path right now
153 // FIXME: use ApiPath instead of String
154 RestconfFuture<OperationOutput> operationsPOST(URI restconfURI, String operation, OperationInputBody body);
157 * Return the revision of {@code ietf-yang-library} module implemented by this server, as defined in
158 * <a href="https://www.rfc-editor.org/rfc/rfc8040#section-3.3.3">RFC8040 {+restconf}/yang-library-version</a>.
160 * @return A {@code yang-library-version} element
162 // FIXME: this is a simple coning-variadic return, similar to how OperationsContent is handled use a common
163 // construct for both cases
164 // FIXME: RestconfFuture if we transition to being used by restconf-client implementation
165 NormalizedNodePayload yangLibraryVersionGET();