1	<?php declare(strict_types=1);
2	/*
3	* This file is part of Aplus Framework Routing Library.
4	*
5	* (c) Natan Felles <natanfelles@gmail.com>
6	*
7	* For the full copyright and license information, please view the LICENSE
8	* file that was distributed with this source code.
9	*/
10	namespace Framework\Routing;
11
12	use Framework\HTTP\Method;
13	use Framework\HTTP\ResponseHeader;
14	use Framework\HTTP\Status;
15
16	/**
17	* Interface ResourceInterface.
18	*
19	* The interface for data management via RESTful APIs
20	* using all correct HTTP methods to manage a resource.
21	*
22	* Note: If a resource needs more than one parameter to get URL path information
23	* provided by placeholders, in addition to $id, do not implement this interface.
24	* But this interface can be a reference because its method names are used in
25	* {@see RouteCollection::resource()}.
26	*
27	* @see https://developer.mozilla.org/en-US/docs/Glossary/REST
28	*
29	* @package routing
30	*/
31	interface ResourceInterface
32	{
33	/**
34	* Handles a GET request for /.
35	*
36	* Common usage: Show a list of paginated items.
37	*
38	* @see Method::GET
39	*
40	* @return mixed
41	*/
42	public function index() : mixed;
43
44	/**
45	* Handles a POST request for /.
46	*
47	* Common usage: Try to create an item. On success, set the Location header to
48	* the 'show' method URL and return a 201 (Created) status code. On fail, return
49	* a 400 (Bad Request) status code and list the error messages in the body.
50	*
51	* @see Method::POST
52	* @see ResourceInterface::show()
53	* @see Status::BAD_REQUEST
54	* @see Status::CREATED
55	* @see ResponseHeader::LOCATION
56	*
57	* @return mixed
58	*/
59	public function create() : mixed;
60
61	/**
62	* Handles a GET request for /$id.
63	*
64	* Common usage: Show a specific item, based on the $id, in the body. If the item
65	* does not exist, return an 404 (Not Found) status code.
66	*
67	* @param string $id
68	*
69	* @see Method::GET
70	* @see Status::NOT_FOUND
71	* @see Status::OK
72	*
73	* @return mixed
74	*/
75	public function show(string $id) : mixed;
76
77	/**
78	* Handles a PATCH request for /$id.
79	*
80	* Common usage: Try to update an item based on the $id. On success return a 200
81	* (OK) status code and set the Location header to the 'show' method URL. On
82	* fail, return a 400 (Bad Request) with the validation errors in the body.
83	*
84	* Note: The HTTP PATCH method allow items to be updated by parts. E.g.
85	* it is possible to update only one, or more, fields in a database table
86	* row.
87	*
88	* @param string $id
89	*
90	* @see Method::PATCH
91	* @see ResourceInterface::show()
92	* @see Status::BAD_REQUEST
93	* @see Status::OK
94	* @see ResponseHeader::LOCATION
95	*
96	* @return mixed
97	*/
98	public function update(string $id) : mixed;
99
100	/**
101	* Handles a PUT request for /$id.
102	*
103	* Common usage: Try to replace an item based on the $id. On success return a 200
104	* (OK) status code and set the Location header to the 'show' method URL. On
105	* fail, return a 400 (Bad Request) with the validation errors in the body.
106	*
107	* Note: The HTTP PUT method requires an entire resource to be updated. E.g.
108	* all fields in a database table row should be updated/replaced.
109	*
110	* @param string $id
111	*
112	* @see Method::PUT
113	* @see ResourceInterface::show()
114	* @see Status::BAD_REQUEST
115	* @see Status::OK
116	* @see ResponseHeader::LOCATION
117	*
118	* @return mixed
119	*/
120	public function replace(string $id) : mixed;
121
122	/**
123	* Handles a DELETE request for /$id.
124	*
125	* Common usage: Delete an item based on the $id. On success, return a 204
126	* (No Content) status code.
127	*
128	* @param string $id
129	*
130	* @see Method::DELETE
131	* @see Status::NO_CONTENT
132	*
133	* @return mixed
134	*/
135	public function delete(string $id) : mixed;
136	}