Adding REST V2 guidelines

redback-integrations/redback-rest/redback-rest-api/src/main/java/org/apache/archiva/redback/rest/api/services/v2/package-info.java

@@ -0,0 +1,102 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * <p>This is the V2 REST API of Redback. It uses JAX-RS annotations for defining the endpoints.
+ * The API is documented with OpenApi annotations.</p>
+ *
+ * <h3>Some design principles of the API and classes:</h3>
+ * <ul>
+ *     <li>All services use V2 model classes. Internal models are always converted to V2 classes.</li>
+ *     <li>Schema attributes use the snake case syntax (lower case with '_' as divider)</li>
+ *     <li>Return code <code>200</code> and <code>201</code> (POST) is used for successful execution.</li>
+ *     <li>Return code <code>403</code> is used, if the user has not the permission for the action.</li>
+ *     <li>Return code <code>422</code> is used for input that has invalid data.</li>
+ * </ul>
+ *
+ * <h4>Querying entity lists</h4>
+ * <p>The main entities of a given path are retrieved on the base path.
+ * Further sub entities or entries may be retrieved via subpaths.
+ * A single entity is returned by the "{id}" path. Be careful with technical paths that are parallel to the
+ * id path. Avoid naming conflicts with the id and technical paths.
+ * Entity attributes may be retrieved by "{id}/{attribute}" path or if there are lists or collections by
+ * "{id}/mycollection/{subentryid}"</p>
+ *
+ * <ul>
+ *  <li><code>GET</code> method is used for retrieving entities on the base path ""</li>
+ *  <li>The query for base entities should always return a paged result and be filterable and sortable</li>
+ *  <li>Query parameters for filtering, ordering and limits should be optional and proper defaults must be set</li>
+ *  <li>Return code <code>200</code> is used for successful retrieval</li>
+ *  <li>This action is idempotent</li>
+ * </ul>
+ *
+ * <h4>Querying single entities</h4>
+ * <p>Single entities are retrieved on the path "{id}"</p>
+ * <ul>
+ *  <li><code>GET</code> method is used for retrieving a single entity. The id is always a path parameter.</li>
+ *  <li>Return code <code>200</code> is used for successful retrieval</li>
+ *  <li>Return code <code>404</code> is used if the entity with the given id does not exist</li>
+ *  <li>This action is idempotent</li>
+ * </ul>
+ *
+ * <h4>Creating entities</h4>
+ * <p>The main entities are created on the base path "".</p>
+ * <ul>
+ *     <li><code>POST</code> is used for creating new entities</li>
+ *     <li>The <code>POST</code> body must always have a complete definition of the entity.</li>
+ *     <li>A unique <code>id</code> or <code>name</code> attribute is required for entities. If the id is generated during POST,
+ *     it must be returned by response body.</li>
+ *     <li>A successful <code>POST</code> request should always return the entity definition as it would be returned by the GET request.</li>
+ *     <li>Return code <code>201</code> is used for successful creation of the new entity.</li>
+ *     <li>A successful response has a <code>Location</code> header with the URL for retrieving the single created entity.</li>
+ *     <li>Return code <code>303</code> is used, if the entity exists already</li>
+ *     <li>This action is not idempotent</li>
+ * </ul>
+ *
+ * <h4>Updating entities</h4>
+ * <p>The path for entity update must contain the '{id}' of the entity. The path should be the same as for the GET operation.</p>
+ * <ul>
+ *     <li><code>PUT</code> is used for updating existing entities</li>
+ *     <li>The body contains a JSON object. Only existing attributes are updated.</li>
+ *     <li>A successful PUT request should return the complete entity definition as it would be returned by the GET request.</li>
+ *     <li>Return code <code>200</code> is used for successful update of the new entity. Even if nothing changed.</li>
+ *     <li>This action is idempotent</li>
+ * </ul>
+ *
+ * <h4>Deleting entities</h4>
+ * <p>The path for entity deletion must contain the '{id}' of the entity. The path should be the same as
+ * for the GET operation.</p>
+ * <ul>
+ *     <li><code>DELETE</code> is used for deleting existing entities</li>
+ *     <li>The successful operation has no request and no response body</li>
+ *     <li>Return code <code>200</code> is used for successful deletion of the new entity.</li>
+ *     <li>This action is not idempotent</li>
+ * </ul>
+ *
+ * <h4>Errors</h4>
+ * <ul>
+ *     <li>A error uses a return code <code>>=400</code> </li>
+ *     <li>All errors use the same result object ({@link org.apache.archiva.rest.api.services.v2.ArchivaRestError}</li>
+ *     <li>Error messages are returned as keys. Translation is part of the client application.</li>
+ * </ul>
+ *
+ * @author Martin Stockhammer <martin_s@apache.org>
+ * @since 3.0
+ */
+package org.apache.archiva.redback.rest.api.services.v2;