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.databind.ChildBody;
18 import org.opendaylight.restconf.nb.rfc8040.databind.DataPostBody;
19 import org.opendaylight.restconf.nb.rfc8040.databind.OperationInputBody;
20 import org.opendaylight.restconf.nb.rfc8040.databind.PatchBody;
21 import org.opendaylight.restconf.nb.rfc8040.databind.ResourceBody;
22 import org.opendaylight.restconf.nb.rfc8040.legacy.NormalizedNodePayload;
23 import org.opendaylight.restconf.server.api.DataPostResult.CreateResource;
24 import org.opendaylight.yangtools.yang.common.Empty;
27 * An implementation of a RESTCONF server, implementing the
28 * <a href="https://www.rfc-editor.org/rfc/rfc8040#section-3.3">RESTCONF API Resource</a>.
30 // FIXME: NETCONF-1207: configuration datastore should maintain ETag and Last-Modified headers, so that these can be
31 // returned when PATCH/POST/PUT modify the data.
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(ApiPath identifier);
44 * Return the content of the datastore.
46 * @param params {@link DataGetParams} for this request
47 * @return A {@link RestconfFuture} of the {@link DataGetResult} content
49 RestconfFuture<DataGetResult> dataGET(DataGetParams params);
52 * Return the content of a data resource.
54 * @param identifier resource identifier
55 * @param params {@link DataGetParams} for this request
56 * @return A {@link RestconfFuture} of the {@link DataGetResult} content
58 RestconfFuture<DataGetResult> dataGET(ApiPath identifier, DataGetParams params);
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(ApiPath 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(ApiPath identifier, PatchBody body);
98 RestconfFuture<CreateResource> dataPOST(ChildBody body, Map<String, String> queryParameters);
100 RestconfFuture<? extends DataPostResult> dataPOST(ApiPath 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(ApiPath identifier, ResourceBody body, Map<String, String> queryParameters);
123 * Return the set of supported RPCs supported by {@link #operationsPOST(URI, ApiPath, OperationInputBody)},
124 * as expressed in the <a href="https://www.rfc-editor.org/rfc/rfc8040#page-84">ietf-restconf.yang</a>
125 * {@code container operations} statement.
127 * @return A {@link RestconfFuture} completing with an {@link OperationsGetResult}
129 RestconfFuture<OperationsGetResult> operationsGET();
132 * Return the details about a particular operation supported by
133 * {@link #operationsPOST(URI, String, OperationInputBody)}, as expressed in the
134 * <a href="https://www.rfc-editor.org/rfc/rfc8040#page-84">ietf-restconfig.yang</a>
135 * {@code container operations} statement.
137 * @param operation An operation
138 * @return A {@link RestconfFuture} completing with an {@link OperationsGetResult}
140 RestconfFuture<OperationsGetResult> operationsGET(ApiPath 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} completing with {@link OperationsPostResult}
151 // FIXME: 'operation' should really be an ApiIdentifier with non-null module, but we also support yang-ext:mount,
152 // and hence it is a path right now
153 RestconfFuture<OperationsPostResult> operationsPOST(URI restconfURI, ApiPath operation, OperationInputBody body);
156 * Return the revision of {@code ietf-yang-library} module implemented by this server, as defined in
157 * <a href="https://www.rfc-editor.org/rfc/rfc8040#section-3.3.3">RFC8040 {+restconf}/yang-library-version</a>.
159 * @return A {@link RestconfFuture} completing with {@link NormalizedNodePayload} containing a single
160 * {@code yang-library-version} leaf element.
162 // FIXME: this is a simple encoding-variadic return, similar to how OperationsContent is handled use a common
163 // construct for both cases -- in this case it carries a yang.common.Revision
164 RestconfFuture<NormalizedNodePayload> yangLibraryVersionGET();
166 RestconfFuture<ModulesGetResult> modulesYangGET(String fileName, @Nullable String revision);
168 RestconfFuture<ModulesGetResult> modulesYangGET(ApiPath mountPath, String fileName, @Nullable String revision);
170 RestconfFuture<ModulesGetResult> modulesYinGET(String fileName, @Nullable String revision);
172 RestconfFuture<ModulesGetResult> modulesYinGET(ApiPath mountPath, String fileName, @Nullable String revision);