shared/api/endpoints/
resource.rs

1use crate::{
2    api::Method,
3    domain::{
4        resource::{
5            ListLikedPath, ListLikedRequest, ListLikedResponse, ResourceAdminDataUpdatePath,
6            ResourceBrowsePath, ResourceBrowseQuery, ResourceBrowseResponse, ResourceClonePath,
7            ResourceCountPath, ResourceCountResponse, ResourceCoverPath, ResourceCreatePath,
8            ResourceCreateRequest, ResourceDeleteAllPath, ResourceDeletePath, ResourceGetDraftPath,
9            ResourceGetLivePath, ResourceId, ResourceLikePath, ResourceLikedPath,
10            ResourceLikedResponse, ResourcePublishPath, ResourceResponse, ResourceSearchPath,
11            ResourceSearchQuery, ResourceSearchResponse, ResourceUnlikePath,
12            ResourceUpdateAdminDataRequest, ResourceUpdateDraftDataPath,
13            ResourceUpdateDraftDataRequest, ResourceViewPath,
14        },
15        CreateResponse,
16    },
17    error::{EmptyError, MetadataNotFound},
18};
19
20use super::ApiEndpoint;
21
22/// Endpoints for resource curation.
23pub mod curation;
24
25/// Endpoints for resource reports.
26pub mod report;
27
28/// Create a Resource and it's draft and live data copies.
29///
30/// * New resources are all set to `PrivacyLevel::Unlisted` by default
31///
32/// # Flow:
33/// 1. Create a Resource and its two data copies with [`Create`]
34/// 2. Optionally update Resource info such as privacy, author with [`Update`]
35/// 3. Make updates to draft data:
36///     a. Patch Resource data through [`UpdateDraftData`]
37///     b. Modify modules, through [`module::Update`]
38/// 4. Finalize draft changes by calling [`Publish`]
39///
40/// # Authorization
41/// * One of `Admin`, `AdminResource`, or `ManageSelfResource`
42pub struct Create;
43impl ApiEndpoint for Create {
44    type Path = ResourceCreatePath;
45    type Req = ResourceCreateRequest;
46    type Res = CreateResponse<ResourceId>;
47    type Err = MetadataNotFound;
48    const METHOD: Method = Method::Post;
49}
50
51/// Get a Resource's live data by ID.
52///
53/// # Authorization
54/// * None
55///
56/// # Errors
57/// * [`NotFound`](http::StatusCode::NOT_FOUND) if the module does not exist, or the parent resource doesn't exist.
58pub struct GetLive;
59impl ApiEndpoint for GetLive {
60    type Path = ResourceGetLivePath;
61    type Req = ();
62    type Res = ResourceResponse;
63    type Err = EmptyError;
64    const METHOD: Method = Method::Get;
65}
66
67/// Get a Resource's draft data by ID.
68///
69/// # Authorization
70/// * One of `Admin`, `AdminResource`,, or `ManageSelfResource` for owned Resources
71///
72/// # Errors
73/// * [`Unauthorized`](http::StatusCode::UNAUTHORIZED) if authorization is not valid.
74/// * [`NotFound`](http::StatusCode::NOT_FOUND) if the module does not exist, or the parent resource doesn't exist.
75pub struct GetDraft;
76impl ApiEndpoint for GetDraft {
77    type Path = ResourceGetDraftPath;
78    type Req = ();
79    type Res = ResourceResponse;
80    type Err = EmptyError;
81    const METHOD: Method = Method::Get;
82}
83
84/// Update the draft data of a Resource.
85///
86/// Note that a copy of the Resource's draft or live data can not be fetched directly, but only as a part
87/// of one of the following routes:
88/// * [`GetLive`] fetches live copies
89/// * [`Search`]
90///
91/// See [`ResourceData`](crate::domain::resource::ResourceData) for the over-the-wire representation.
92///
93/// # Authorization
94/// * One of `Admin`, `AdminResource`,, or `ManageSelfResource` for owned Resources
95pub struct UpdateDraftData;
96impl ApiEndpoint for UpdateDraftData {
97    type Path = ResourceUpdateDraftDataPath;
98    type Req = ResourceUpdateDraftDataRequest;
99    type Res = ();
100    type Err = MetadataNotFound;
101    const METHOD: Method = Method::Patch;
102}
103
104/// Publish a Resource draft to live by copying over the Resource and module data.
105///
106/// # Authorization
107/// * None
108pub struct Publish;
109impl ApiEndpoint for Publish {
110    type Path = ResourcePublishPath;
111    type Req = ();
112    type Res = ();
113    type Err = EmptyError;
114    const METHOD: Method = Method::Put;
115}
116
117/// Browse Resources. Returns the draft data copies in the response.
118///
119/// # Authorization
120/// * One of `Admin`, `AdminResource`, or `ManageSelfResource`
121pub struct Browse;
122impl ApiEndpoint for Browse {
123    type Path = ResourceBrowsePath;
124    type Req = ResourceBrowseQuery;
125    type Res = ResourceBrowseResponse;
126    type Err = EmptyError;
127    const METHOD: Method = Method::Get;
128}
129
130/// Search for Resources.
131///
132/// # Authorization
133/// * None
134pub struct Search;
135impl ApiEndpoint for Search {
136    type Path = ResourceSearchPath;
137    type Req = ResourceSearchQuery;
138    type Res = ResourceSearchResponse;
139    type Err = EmptyError;
140    const METHOD: Method = Method::Get;
141}
142
143/// Clone a Resource. This clones both the draft and live.
144///
145/// # Authorization
146/// * One of `Admin`, `AdminResource`, or `ManageSelfResource`
147///
148/// # Errors
149/// * [`Unauthorized`](http::StatusCode::UNAUTHORIZED) if authorization is not valid.
150/// * [`Forbidden`](http::StatusCode::FORBIDDEN) if the user does not have sufficient permission to perform the action.
151/// * ['NotFound'](http::StatusCode::NOT_FOUND) if the resource does not exist.
152/// * ['BadRequest'](http::StatusCode::BAD_REQUEST) if the request is malformed or the Resource is a draft.
153pub struct Clone;
154impl ApiEndpoint for Clone {
155    type Path = ResourceClonePath;
156    type Req = ();
157    type Res = CreateResponse<ResourceId>;
158    type Err = EmptyError;
159    const METHOD: Method = Method::Post;
160}
161
162/// Delete a Resource.
163///
164/// # Authorization
165/// * One of `Admin`, `AdminResource`, or `ManageSelfResource` for owned Resources
166pub struct Delete;
167impl ApiEndpoint for Delete {
168    type Path = ResourceDeletePath;
169    type Req = ();
170    type Res = ();
171    type Err = EmptyError;
172    const METHOD: Method = Method::Delete;
173}
174
175/// Delete all resources associated with current user.
176///
177/// # Authorization
178/// * One of `Admin`, `AdminResource`, or `ManageSelfResource` for owned Resources
179pub struct DeleteAll;
180impl ApiEndpoint for DeleteAll {
181    type Path = ResourceDeleteAllPath;
182    type Req = ();
183    type Res = ();
184    type Err = EmptyError;
185    const METHOD: Method = Method::Delete;
186}
187
188/// Indicates that a resource has a cover
189///
190/// # Authorization
191/// * One of `Admin`, `AdminResource`, or `ManageSelfResource` for owned Resources
192pub struct Cover;
193impl ApiEndpoint for Cover {
194    type Path = ResourceCoverPath;
195    type Req = ();
196    type Res = ();
197    type Err = EmptyError;
198    const METHOD: Method = Method::Patch;
199}
200
201/// Count of all public Resources. See [`PrivacyLevel`](crate::domain::resource::PrivacyLevel).
202///
203/// # Authorization
204/// * None
205pub struct Count;
206impl ApiEndpoint for Count {
207    type Path = ResourceCountPath;
208    type Req = ();
209    type Res = ResourceCountResponse;
210    type Err = EmptyError;
211    const METHOD: Method = Method::Get;
212}
213
214/// Like a Resource
215///
216/// # Authorization
217/// * Admin, BasicAuth
218pub struct Like;
219impl ApiEndpoint for Like {
220    type Path = ResourceLikePath;
221    type Req = ();
222    type Res = ();
223    type Err = EmptyError;
224    const METHOD: Method = Method::Put;
225}
226
227/// Unlike a Resource
228///
229/// # Authorization
230/// * Admin, BasicAuth
231pub struct Unlike;
232impl ApiEndpoint for Unlike {
233    type Path = ResourceUnlikePath;
234    type Req = ();
235    type Res = ();
236    type Err = EmptyError;
237    const METHOD: Method = Method::Delete;
238}
239
240/// Is a Resource liked by a user
241///
242/// # Authorization
243/// * Admin, BasicAuth
244pub struct Liked;
245impl ApiEndpoint for Liked {
246    type Path = ResourceLikedPath;
247    type Req = ();
248    type Res = ResourceLikedResponse;
249    type Err = EmptyError;
250    const METHOD: Method = Method::Get;
251}
252
253/// List user's liked resources.
254pub struct ListLiked;
255impl ApiEndpoint for ListLiked {
256    type Req = ListLikedRequest;
257    type Res = ListLikedResponse;
258    type Path = ListLikedPath;
259    type Err = EmptyError;
260    const METHOD: Method = Method::Get;
261}
262
263/// View a Resource
264///
265/// # Authorization
266/// * None
267pub struct View;
268impl ApiEndpoint for View {
269    type Path = ResourceViewPath;
270    type Req = ();
271    type Res = ();
272    type Err = EmptyError;
273    const METHOD: Method = Method::Put;
274}
275
276/// Update an admin data for a Resource.
277///
278/// # Authorization
279///
280/// * Standard + [`UserScope::ManageResource`](crate::domain::user::UserScope)
281///
282/// # Errors
283///
284/// * [`Unauthorized`](http::StatusCode::UNAUTHORIZED) if authorization is not valid.
285/// * [`Forbidden`](http::StatusCode::FORBIDDEN) if the user does not have sufficient permission to perform the action.
286/// * [`BadRequest`](http::StatusCode::BAD_REQUEST) if the request is missing/invalid.
287pub struct ResourceAdminDataUpdate;
288impl ApiEndpoint for ResourceAdminDataUpdate {
289    type Path = ResourceAdminDataUpdatePath;
290    type Req = ResourceUpdateAdminDataRequest;
291    type Res = ();
292    type Err = EmptyError;
293    const METHOD: Method = Method::Patch;
294}