source.dussan.org Git - archiva.git/blob

   1 /*
   2  * Licensed to the Apache Software Foundation (ASF) under one
   3  * or more contributor license agreements.  See the NOTICE file
   4  * distributed with this work for additional information
   5  * regarding copyright ownership.  The ASF licenses this file
   6  * to you under the Apache License, Version 2.0 (the
   7  * "License"); you may not use this file except in compliance
   8  * with the License.  You may obtain a copy of the License at
   9  *
  10  *   http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing,
  13  * software distributed under the License is distributed on an
  14  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  15  * KIND, either express or implied.  See the License for the
  16  * specific language governing permissions and limitations
  17  * under the License.
  18  */
  19
  20 /**
  21  * <p>This is the V2 REST API of Archiva. It uses JAX-RS annotations for defining the endpoints.
  22  * The API is documented with OpenApi annotations.</p>
  23  *
  24  * <h3>Some design principles of the API and classes:</h3>
  25  * <ul>
  26  *     <li>All services use V2 model classes. Internal models are always converted to V2 classes.</li>
  27  *     <li>Schema attributes use the snake case syntax (lower case with '_' as divider)</li>
  28  *     <li>Return code <code>200</code> and <code>201</code> (POST) is used for successful execution.</li>
  29  *     <li>Return code <code>403</code> is used, if the user has not the permission for the action.</li>
  30  *     <li>Return code <code>422</code> is used for input that has invalid data.</li>
  31  * </ul>
  32  *
  33  * <h4>Querying entity lists</h4>
  34  * <p>The main entities of a given path are retrieved on the base path.
  35  * Further sub entities or entries may be retrieved via subpaths.
  36  * A single entity is returned by the "{id}" path. Be careful with technical paths that are parallel to the
  37  * id path. Avoid naming conflicts with the id and technical paths.
  38  * Entity attributes may be retrieved by "{id}/{attribute}" path or if there are lists or collections by
  39  * "{id}/mycollection/{subentryid}"</p>
  40  *
  41  * <ul>
  42  *  <li><code>GET</code> method is used for retrieving entities on the base path ""</li>
  43  *  <li>The query for base entities should always return a paged result and be filterable and sortable</li>
  44  *  <li>Query parameters for filtering, ordering and limits should be optional and proper defaults must be set</li>
  45  *  <li>Return code <code>200</code> is used for successful retrieval</li>
  46  *  <li>This action is idempotent</li>
  47  * </ul>
  48  *
  49  * <h4>Querying single entities</h4>
  50  * <p>Single entities are retrieved on the path "{id}"</p>
  51  * <ul>
  52  *  <li><code>GET</code> method is used for retrieving a single entity. The id is always a path parameter.</li>
  53  *  <li>Return code <code>200</code> is used for successful retrieval</li>
  54  *  <li>Return code <code>404</code> is used if the entity with the given id does not exist</li>
  55  *  <li>This action is idempotent</li>
  56  * </ul>
  57  *
  58  * <h4>Creating entities</h4>
  59  * <p>The main entities are created on the base path "".</p>
  60  * <ul>
  61  *     <li><code>POST</code> is used for creating new entities</li>
  62  *     <li>The <code>POST</code> body must always have a complete definition of the entity.</li>
  63  *     <li>A unique <code>id</code> or <code>name</code> attribute is required for entities. If the id is generated during POST,
  64  *     it must be returned by response body.</li>
  65  *     <li>A successful <code>POST</code> request should always return the entity definition as it would be returned by the GET request.</li>
  66  *     <li>Return code <code>201</code> is used for successful creation of the new entity.</li>
  67  *     <li>A successful response has a <code>Location</code> header with the URL for retrieving the single created entity.</li>
  68  *     <li>Return code <code>303</code> is used, if the entity exists already</li>
  69  *     <li>This action is not idempotent</li>
  70  * </ul>
  71  *
  72  * <h4>Updating entities</h4>
  73  * <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>
  74  * <ul>
  75  *     <li><code>PUT</code> is used for updating existing entities</li>
  76  *     <li>The body contains a JSON object. Only existing attributes are updated.</li>
  77  *     <li>A successful PUT request should return the complete entity definition as it would be returned by the GET request.</li>
  78  *     <li>Return code <code>200</code> is used for successful update of the new entity. Even if nothing changed.</li>
  79  *     <li>This action is idempotent</li>
  80  * </ul>
  81  *
  82  * <h4>Deleting entities</h4>
  83  * <p>The path for entity deletion must contain the '{id}' of the entity. The path should be the same as
  84  * for the GET operation.</p>
  85  * <ul>
  86  *     <li><code>DELETE</code> is used for deleting existing entities</li>
  87  *     <li>The successful operation has no request and no response body</li>
  88  *     <li>Return code <code>200</code> is used for successful deletion of the new entity.</li>
  89  *     <li>This action is not idempotent</li>
  90  * </ul>
  91  *
  92  * <h4>Errors</h4>
  93  * <ul>
  94  *     <li>A error uses a return code <code>>=400</code> </li>
  95  *     <li>All errors use the same result object ({@link org.apache.archiva.rest.api.services.v2.ArchivaRestError}</li>
  96  *     <li>Error messages are returned as keys. Translation is part of the client application.</li>
  97  * </ul>
  98  *
  99  * @author Martin Stockhammer <martin_s@apache.org>
 100  * @since 3.0
 101  */
 102 package org.apache.archiva.rest.api.services.v2;