restful-template/response-template

A response interface builder for REST API

0.0.3 2021-03-25 01:08 UTC

Requires

• php: ^7.2

Requires (Dev)

• phpunit/phpunit: ^9.5

GPL-3.0-or-later

• Enrique René Beauxis Reyes

• restful
• http response
• REST API

README

A response interface builder for REST API.

Table of Contents

• Installation
• Usage
  • Simples Case
  • Data in Response
  • Links Setup
• Plan
• Support
• Contribute

Installation

There are some installation ways. You can choose the best way for you.

Composer (recommended)

This way requires Composer:

$ composer require restful-template/response-template

Git

Clone the repo into your project:

$ git clone https://github.com/enriquerene/response-template.git

Zip

Dowload the package and uncpack it into your project: Dowload ZIP

Usage

ResponseTemplate requires an valid HTTP Status Code. Refer to section 10 of RFC 2616.

Simplest Case

The simplest case is to instantiate the class ResponseTemplate with HTTP Status Code "200 Ok." and call method build:

<?php
use RESTfulTemplate\ResponseTemplate;

$rest = new ResponseTemplate( 200 );
$response = $rest->build();
// $response contains following array:
// [
// 	"status" => [
// 		"code" => 200,
// 		"message" => "Ok."
// 	],
// 	"data" => null,
// 	"links" => [
// 		"self" => [
//			"url" => "https://example.com/",
//			"method" => "GET"
//		]
// 	]
// ];

Data in Response

It's possible insert data to response at the build moment:

<?php
use RESTfulTemplate\ResponseTemplate;

$product = [
	"id" => 1,
	"name" => "product-name",
	"displayName" => "Product Name",
	"price" => "14.50",
	"stock" => 20
];

$rest = new ResponseTemplate( 200 );
$response = $rest->build( $product );
// $response contains following array:
// [
// 	"status" => [
// 		"code" => 200,
// 		"message" => "Ok."
// 	],
// 	"data" => [
//		"id" => 1,
// 		"name" => "product-name",
// 		"displayName" => "Product Name",
// 		"price" => "14.50",
// 		"stock" => 20
// 	],
// 	"links" => [
// 		"self" => [
//			"url" => "https://example.com/products/1",
//			"method" => "GET"
//		]
// 	]
// ];

Links Setup

You can make use of setLink method to setup a link to response:

<?php
use RESTfulTemplate\ResponseTemplate;

$products = [
	[
		"id" => 1,
		"name" => "product-name",
		"displayName" => "Product Name",
		"price" => "14.50",
		"stock" => 20
	],
	/* ...more ones */
];

$rest = new ResponseTemplate( 200 );
$rest = $rest->setLink( "next", "https://example.com/products?page=2" );
$response = $rest->build( $products );
// $response contains following array:
// [
// 	"status" => [
// 		"code" => 200,
// 		"message" => "Ok."
// 	],
// 	"data" => [
//		[
//			"id" => 1,
//			"name" => "product-name",
//			"displayName" => "Product Name",
//			"price" => "14.50",
//			"stock" => 20
//		],
// 		/* ...more ones */
//	],
// 	"links" => [
// 		"self" => [
//			"url" => "https://example.com/products",
//			"method" => "GET"
//		],
// 		"next" => [
//			"url" => "https://example.com/products?page=2",
//			"method" => "GET"
//		]
// 	]
// ];

It's possible insert a third argument into setLink method to define "method" property of link. If you want work with a POST route, for example, you probrably would like to use $rest = $rest->setLink( "create", "/products", "POST" );.

Plan

This project aims to be up to date with standards. Future version may be aligned to RFC 7231. Some implementation in the roadmap:

Setting custom link key

• If just the query string starting with ? is given, the same basename and path will be retrieved as in self url.
• If just the path is given, the same basename will be retrieved as in self url.
• If a basename including . is given, the same protocol will be retrieved as in self url.
• Given full path including http/https protocol will be placed as it is into custom key url property.

Support

If you need some help you can open an issue.

Contribute

Do a pull request or send email to Support.