/*
* Copyright (c) 2023 PANTHEON.tech, s.r.o. and others. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v1.0 which accompanies this distribution,
* and is available at http://www.eclipse.org/legal/epl-v10.html
*/
package org.opendaylight.restconf.server.api;
import java.net.URI;
import java.util.Map;
import org.eclipse.jdt.annotation.NonNullByDefault;
import org.eclipse.jdt.annotation.Nullable;
import org.opendaylight.restconf.api.ApiPath;
import org.opendaylight.restconf.common.errors.RestconfFuture;
import org.opendaylight.restconf.nb.rfc8040.legacy.NormalizedNodePayload;
import org.opendaylight.yangtools.yang.common.Empty;
/**
* An implementation of a RESTCONF server, implementing the
* RESTCONF API Resource.
*/
@NonNullByDefault
public interface RestconfServer {
/**
* Delete a data resource.
*
* @param identifier resource identifier
* @return A {@link RestconfFuture} of the operation
*/
@SuppressWarnings("checkstyle:abbreviationAsWordInName")
RestconfFuture dataDELETE(ApiPath identifier);
/**
* Return the content of the datastore.
*
* @param params {@link DataGetParams} for this request
* @return A {@link RestconfFuture} of the {@link DataGetResult} content
*/
RestconfFuture dataGET(DataGetParams params);
/**
* Return the content of a data resource.
*
* @param identifier resource identifier
* @param params {@link DataGetParams} for this request
* @return A {@link RestconfFuture} of the {@link DataGetResult} content
*/
RestconfFuture dataGET(ApiPath identifier, DataGetParams params);
/**
* Partially modify the target data resource, as defined in
* RFC8040, section 4.6.1.
*
* @param body data node for put to config DS
* @return A {@link RestconfFuture} of the operation
*/
RestconfFuture dataPATCH(ResourceBody body);
/**
* Partially modify the target data resource, as defined in
* RFC8040, section 4.6.1.
*
* @param identifier resource identifier
* @param body data node for put to config DS
* @return A {@link RestconfFuture} of the operation
*/
RestconfFuture dataPATCH(ApiPath identifier, ResourceBody body);
/**
* Ordered list of edits that are applied to the datastore by the server, as defined in
* RFC8072, section 2.
*
* @param body YANG Patch body
* @return A {@link RestconfFuture} of the {@link DataYangPatchResult} content
*/
RestconfFuture dataPATCH(PatchBody body);
/**
* Ordered list of edits that are applied to the datastore by the server, as defined in
* RFC8072, section 2.
*
* @param identifier path to target
* @param body YANG Patch body
* @return A {@link RestconfFuture} of the {@link DataYangPatchResult} content
*/
RestconfFuture dataPATCH(ApiPath identifier, PatchBody body);
RestconfFuture dataPOST(ChildBody body, Map queryParameters);
/**
* Create or invoke a operation, as described in
* RFC8040 section 4.4.
*
* @param identifier path to target
* @param body body of the post request
* @param queryParameters query parameters
*/
RestconfFuture extends DataPostResult> dataPOST(ApiPath identifier, DataPostBody body,
Map queryParameters);
/**
* Replace the data store, as described in
* RFC8040 section 4.5.
*
* @param body data node for put to config DS
* @param queryParameters Query parameters
* @return A {@link RestconfFuture} completing with {@link DataPutResult}
*/
RestconfFuture dataPUT(ResourceBody body, Map queryParameters);
/**
* Create or replace a data store resource, as described in
* RFC8040 section 4.5.
*
* @param identifier resource identifier
* @param body data node for put to config DS
* @param queryParameters Query parameters
* @return A {@link RestconfFuture} completing with {@link DataPutResult}
*/
RestconfFuture dataPUT(ApiPath identifier, ResourceBody body, Map queryParameters);
/**
* Return the set of supported RPCs supported by {@link #operationsPOST(URI, ApiPath, Map, OperationInputBody)},
* as expressed in the ietf-restconf.yang
* {@code container operations} statement.
*
* @return A {@link RestconfFuture} completing with an {@link FormattableBody}
*/
RestconfFuture operationsGET();
/*
* Return the details about a particular operation supported by
* {@link #operationsPOST(URI, String, OperationInputBody)}, as expressed in the
* ietf-restconfig.yang
* {@code container operations} statement.
*
* @param operation An operation
* @return A {@link RestconfFuture} completing with an {@link FormattableBody}
*/
RestconfFuture operationsGET(ApiPath operation);
/**
* Invoke an RPC operation, as defined in
* RFC8040 Operation Resource.
*
* @param restconfURI Base URI of the request
* @param operation {@code } path, really an {@link ApiPath} to an {@code rpc}
* @param queryParameters query parameters
* @param body RPC operation
* @return A {@link RestconfFuture} completing with {@link InvokeResult}
*/
// FIXME: 'operation' should really be an ApiIdentifier with non-null module, but we also support yang-ext:mount,
// and hence it is a path right now
RestconfFuture operationsPOST(URI restconfURI, ApiPath operation, Map queryParameters,
OperationInputBody body);
/**
* Return the revision of {@code ietf-yang-library} module implemented by this server, as defined in
* RFC8040 {+restconf}/yang-library-version.
*
* @return A {@link RestconfFuture} completing with {@link NormalizedNodePayload} containing a single
* {@code yang-library-version} leaf element.
*/
// FIXME: this is a simple encoding-variadic return, similar to how OperationsContent is handled use a common
// construct for both cases -- in this case it carries a yang.common.Revision
RestconfFuture yangLibraryVersionGET();
RestconfFuture modulesYangGET(String fileName, @Nullable String revision);
RestconfFuture modulesYangGET(ApiPath mountPath, String fileName, @Nullable String revision);
RestconfFuture modulesYinGET(String fileName, @Nullable String revision);
RestconfFuture modulesYinGET(ApiPath mountPath, String fileName, @Nullable String revision);
}