{"id":18550310,"url":"https://github.com/xp-forge/rest-api","last_synced_at":"2025-07-14T23:03:33.987Z","repository":{"id":57084822,"uuid":"119896279","full_name":"xp-forge/rest-api","owner":"xp-forge","description":"REST APIs","archived":false,"fork":false,"pushed_at":"2025-05-04T16:51:16.000Z","size":226,"stargazers_count":2,"open_issues_count":3,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-06-09T10:35:16.982Z","etag":null,"topics":["annotations","asynchronous","http","json","matrix-parameters","no-xml","rest-api","xp-framework"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xp-forge.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-02-01T21:33:02.000Z","updated_at":"2025-05-04T16:51:19.000Z","dependencies_parsed_at":"2025-04-09T22:31:30.808Z","dependency_job_id":null,"html_url":"https://github.com/xp-forge/rest-api","commit_stats":null,"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/xp-forge/rest-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xp-forge%2Frest-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xp-forge%2Frest-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xp-forge%2Frest-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xp-forge%2Frest-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xp-forge","download_url":"https://codeload.github.com/xp-forge/rest-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xp-forge%2Frest-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265365543,"owners_count":23753349,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotations","asynchronous","http","json","matrix-parameters","no-xml","rest-api","xp-framework"],"created_at":"2024-11-06T21:04:11.242Z","updated_at":"2025-07-14T23:03:33.978Z","avatar_url":"https://github.com/xp-forge.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Rest APIs\n========================================================================\n\n[![Build status on GitHub](https://github.com/xp-forge/rest-api/workflows/Tests/badge.svg)](https://github.com/xp-forge/rest-api/actions)\n[![XP Framework Module](https://raw.githubusercontent.com/xp-framework/web/master/static/xp-framework-badge.png)](https://github.com/xp-framework/core)\n[![BSD Licence](https://raw.githubusercontent.com/xp-framework/web/master/static/licence-bsd.png)](https://github.com/xp-framework/core/blob/master/LICENCE.md)\n[![Requires PHP 7.4+](https://raw.githubusercontent.com/xp-framework/web/master/static/php-7_4plus.svg)](http://php.net/)\n[![Supports PHP 8.0+](https://raw.githubusercontent.com/xp-framework/web/master/static/php-8_0plus.svg)](http://php.net/)\n[![Latest Stable Version](https://poser.pugx.org/xp-forge/rest-api/version.svg)](https://packagist.org/packages/xp-forge/rest-api)\n\nAnnotation-based REST APIs\n\nExample\n-------\n\n```php\nuse web\\rest\\{Get, Post, Resource, Response};\n\n#[Resource('/users')]\nclass Users {\n\n  #[Get('/')]\n  public function listUsers($max= 10) {\n    // $max comes from request parameter \"max\", defaulting to 10\n    // ...\n  }\n\n  #[Get('/{id}')]\n  public function findUser($id) {\n    // $id is extracted from URL segment\n    // ...\n  }\n\n  #[Post('/')]\n  public function createUser($user) {\n    // $user is deserialized from the request body according to its content type\n    // ...\n    return Response::created('/users/{id}', $id)-\u003eentity($created);\n  }\n}\n```\n\nWire it together in a web application:\n\n```php\nuse web\\Application;\n\nclass Service extends Application {\n\n  /** @return [:var] */\n  public function routes() {\n    return ['/users' =\u003e new RestApi(new Users())];\n  }\n}\n```\n\nRun it using:\n\n```bash\n$ xp -supervise web Service\n@xp.web.Serve(HTTP @ peer.ServerSocket(resource(type= Socket, id= 88) -\u003e tcp://127.0.0.1:8080))\n# ...\n```\n\nThen call `curl -i localhost:8080/users/1549`.\n\nParameter sources\n-----------------\n\nMethod parameters are automatically extracted from URI segments if their name matches the path segment in the curly braces. For requests without bodies (GET, HEAD, DELETE, OPTIONS), the value is extracted from request parameters. For requests with bodies (POST, PUT and PATCH), the body is deserialized and passed.\n\nTo supply the source explicitely, you can use parameter attributes:\n\n* `#[Param]` will fetch the parameter from the request parameter named \"max\".\n* `#[Param('maximum')]` will fetch the parameter from the request parameter named \"maximum\".\n* `#[Value]` will use a request value (which was previously passed e.g. inside a filter via `pass()`) for the parameter\n* `#[Header('Content-Type')]` will use the *Content-Type* header as value for the parameter\n* `#[Entity]` will deserialize the request body and pass its value to the parameter\n* `#[Body]` will pass the request body as a string\n* `#[Stream]` will pass an `io.streams.InputStream` instance to stream the request body to the parameter\n* `#[Request]` will pass the complete `web.Request` object\n\nParameter conversions\n---------------------\n\nParameters can be converted from their input. This library comes with a built-in conversion named *SeparatedBy*:\n\n```php\nuse web\\rest\\{Resource, Get, Param, SeparatedBy};\n\n#[Resource('/api/trainings')]\nclass Trainings {\n\n  #[Get('/completed')]\n  public function completed(#[Param, SeparatedBy(',')] array $orgunits) {\n    return $this-\u003erepository-\u003efind(['status' =\u003e 'COMPLETED', 'orgunits' =\u003e $orgunits]);\n  }\n}\n```\n\nThe *orgunits* parameter can now be supplied in the URL as follows: `https://example.com/api/trainings/completed?orgunits=A,B` and the resulting value inside *$orgunits* will be `[\"A\", \"B\"]`. User-defined conversions can be supplied by implementing the `web.rest.Conversion` interface.\n\nMatrix parameters\n-----------------\n\nThis library supports parameters inside path segments, e.g. `https://example.com/api/trainings/status=COMPLETED;orgunits=A,B/authors`:\n\n```php\nuse web\\rest\\{Resource, Get, Matrix};\n\n#[Resource('/api/trainings')]\nclass Trainings {\n\n  #[Get('/{filter}/authors')]\n  public function authors(#[Matrix] array $filter) {\n    $authors= [];\n    foreach ($this-\u003erepository-\u003efind($filter) as $training) {\n      $authors[$training-\u003eauthor-\u003eid()]= $training-\u003eauthor;\n    }\n    return $authors;\n  }\n}\n```\n\nThe resulting value inside *$filter* will be `[\"status\" =\u003e \"COMPLETED\", \"orgunits\" =\u003e [\"A\", \"B\"]]`.\n\nReturn types\n------------\n\nMethods can return anything, which is then serialized and written to the response with a \"200 OK\" status. If you want greater control over the response, you can use the `web.rest.Response` class. It provides a fluent DSL for handling various scenarios.\n\nExample:\n\n```php\nreturn Response::created('/users/{id}', $id)-\u003etype('application/vnd.example.type-v2+json')-\u003eentity($user);\n```\n\nCreation:\n\n* `Response::ok()` - 200 OK\n* `Response::created([string $location])` - 201 Created, optionally with a *Location* header\n* `Response::noContent()` - 204 No content\n* `Response::see(string $location)` - 302 Found and a *Location* header\n* `Response::notModified()` - 304 Not modified\n* `Response::notFound([string $message])` - 404 Not found and an optional message, which is serialized\n* `Response::notAcceptable([string $message])` - 406 Not acceptable and an optional message, which is serialized\n* `Response::error(int $code[, string $message])` - An error and an optional message, which is serialized\n* `Response::status(int $code)` - Any other status code\n\nHeaders:\n\n* `$response-\u003etype(string $mime)` will set the *Content-Type* header\n* `$response-\u003eheader(string $name, string $value)` will set a header with a given name and value\n\nBody:\n\n* `$response-\u003eentity(var $value)` will sent a value, serializing it\n* `$response-\u003estream(io.streams.InputStream $in[, int $size])` will stream a response\n* `$response-\u003ebody(string $bytes)` will write the given raw bytes to the response\n\nAsynchronous invocation\n-----------------------\n\nThe following code will run the upload function asynchronously, continuing to serve requests while file contents are being transmitted.\n\n```php\nuse io\\Folder;\nuse web\\rest\\{Async, Post, Resource, Response};\n\n#[Resource('/api')]\nclass Uploads {\n  public function __construct(private Folder $folder) { }\n\n  #[Post('/files')]\n  public function upload(#[Request] $req) {\n    return new Async(function() use($req) {\n      if ($multipart= $req-\u003emultipart()) {\n\n        foreach ($multipart-\u003efiles() as $file) {\n          yield from $file-\u003etransmit($this-\u003efolder);\n        }\n      }\n\n      return Response::ok();\n    });\n  }\n}\n```\n\nSee also\n--------\n\nhttps://github.com/thekid/shorturl - URL Shortener service ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxp-forge%2Frest-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxp-forge%2Frest-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxp-forge%2Frest-api/lists"}