2017 © Pedro Peláez
 

library rest-api

Rest API

image

xp-forge/rest-api

Rest API

  • Tuesday, July 17, 2018
  • by thekid
  • Repository
  • 2 Watchers
  • 0 Stars
  • 509 Installations
  • PHP
  • 0 Dependents
  • 0 Suggesters
  • 1 Forks
  • 1 Open issues
  • 15 Versions
  • 138 % Grown

The README.md

Rest APIs

Build Status on TravisCI XP Framework Module BSD Licence Requires PHP 7.0+ Latest Stable Version, (*1)

Annotation-based REST APIs, (*2)

Example

use web\rest\{Get, Post, Resource, Response};

#[Resource('/users')]
class Users {

  #[Get('/')]
  public function listUsers($max= 10) {
    // $max comes from request parameter "max", defaulting to 10
    // ...
  }

  #[Get('/{id}')]
  public function findUser($id) {
    // $id is extracted from URL segment
    // ...
  }

  #[Post('/')]
  public function createUser($user) {
    // $user is deserialized from the request body according to its content type
    // ...
    return Response::created('/users/{id}', $id)->entity($created);
  }
}

Wire it together in a web application:, (*3)

use web\Application;

class Service extends Application {

  /** @return [:var] */
  public function routes() {
    return ['/users' => new RestApi(new Users())];
  }
}

Run it using:, (*4)

$ xp -supervise web Service
@xp.web.Serve(HTTP @ peer.ServerSocket(resource(type= Socket, id= 88) -> tcp://127.0.0.1:8080))
# ...

Then call curl -i localhost:8080/users/1549., (*5)

Parameter sources

Method 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., (*6)

To supply the source explicitely, you can use parameter attributes:, (*7)

  • #[Param] will fetch the parameter from the request parameter named "max".
  • #[Param('maximum')] will fetch the parameter from the request parameter named "maximum".
  • #[Value] will use a request value (which was previously passed e.g. inside a filter via pass()) for the parameter
  • #[Header('Content-Type')] will use the Content-Type header as value for the parameter
  • #[Entity] will deserialize the request body and pass its value to the parameter
  • #[Body] will pass the request body as a string
  • #[Stream] will pass an io.streams.InputStream instance to stream the request body to the parameter
  • #[Request] will pass the complete web.Request object

Return types

Methods 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., (*8)

Example:, (*9)

return Response::created('/users/{id}', $id)->type('application/vnd.example.type-v2+json')->entity($user);

Creation:, (*10)

  • Response::ok() - 200 OK
  • Response::created([string $location]) - 201 Created, optionally with a Location header
  • Response::noContent() - 204 No content
  • Response::see(string $location) - 302 Found and a Location header
  • Response::notModified() - 304 Not modified
  • Response::notFound([string $message]) - 404 Not found and an optional message, which is serialized
  • Response::notAcceptable([string $message]) - 406 Not acceptable and an optional message, which is serialized
  • Response::error(int $code[, string $message]) - An error and an optional message, which is serialized
  • Response::status(int $code) - Any other status code

Headers:, (*11)

  • $response->type(string $mime) will set the Content-Type header
  • $response->header(string $name, string $value) will set a header with a given name and value

Body:, (*12)

  • $response->entity(var $value) will sent a value, serializing it
  • $response->stream(io.streams.InputStream $in[, int $size]) will stream a response
  • $response->body(string $bytes) will write the given raw bytes to the response

See also

https://github.com/thekid/shorturl - URL Shortener service, (*13)

The Versions

17/07 2018

dev-master

9999999-dev http://xp-framework.net/

Rest API

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

module xp

17/07 2018
17/07 2018

dev-feature/classes-in

dev-feature/classes-in http://xp-framework.net/

Rest API

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

module xp

17/07 2018

dev-feature/x-www-form-urlencoded

dev-feature/x-www-form-urlencoded http://xp-framework.net/

Rest API

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

module xp

17/07 2018
25/05 2018
25/05 2018

dev-feature/invocations

dev-feature/invocations http://xp-framework.net/

Rest API

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

module xp

23/05 2018
10/04 2018
20/02 2018
20/02 2018
13/02 2018
13/02 2018
13/02 2018
12/02 2018