@innoflash/laravel-utils v1.0.5

LaravelUtils

This library is basically mapping the most common Laravel API responses to an Angular project

Table of contents

• Installation
• Usage
  • Models
    • JWToken
    • Date
    • Pagination
      • Links
      • Meta
  • API Responses
    • Action Response
    • Error Response
    • Auth Response
    • Collection Response
    • Paginated Response

Installion

npm install @innoflash/laravel-utils

Usage

PS. Note that you can always customise the response by extending the interface to modify params according to your suit.

All the responses passing extra data have keys named data but you can extend and override the key if you are wrapping your data with another key

MODELS

JWToken

This is used to map API JWT token into the project

• Used on login
• Used on token refresh

JSON Response:

{
  "access_token": "access_token",
  "expires_in": 7200,
  "type": "bearer"
}

JWToken

Property	Type	Availability	Description
access_token	string	mandatory	The JSON Web Token to be used as a header on accessing the other middleware protected routes.
expires_in	number	mandatory	The number of seconds the token is alive
type	string	mandatory	The token type.

Date

Used on manipulating date responses.

JSON Response.

    {
        "approx": "3 hours ago",
        "formatted": "Mon 01 Jun 2020",
        "exact": "2020-06-01T12:46:28.000000Z",
        "time": "12:46"
     }

Date

Property	Type	Availability	Description
approx	string	mandatory	The time in human readable form.
formatted	string	mandatory	The date time in a formatted style. (Just the date)
exact	string	mandatory	The date time as extracted from the DB.
time	string	mandatory	The date time in a formatted style. (Just the time)

Pagination

This handles paginated data.

Links

Maps the links from pagination.

JSON Response.

{
    "first": "http://localhost:8000/api/users?page=1",
    "last": "http://localhost:8000/api/users?page=5",
    "prev": null,
    "next": "http://localhost:8000/api/users?page=2"
  }

Links

Property	Type	Availability	Description
first	string	mandatory	Link to the first page of the pagination.
last	string	mandatory	Link to the last page of the pagination.
prev	string	mandatory	Link to the previous page of the pagination.
next	string	mandatory	Link to the next page of the pagination.

Meta

Maps the meta data passed from pagination.

JSON Response.

{
    "current_page": 1,
    "from": 3,
    "last_page": 5,
    "path": "http://localhost:8000/api/users",
    "per_page": 20,
    "to": 20,
    "total": 99
  }

Meta

Property	Type	Availability	Description
current_page	number	mandatory	The current page in the paginated data.
from	number	mandatory	The number from which pagination is counting paginated data.
last_page	number	mandatory	The last possible page number from paginated data.
path	number	mandatory	The url being appended some page data.
to	number	mandatory	The number to which pagination is counting paginated data.
total	number	mandatory	The total number of items in the paginated data.

API RESPONSES

Action Response

Used mainly for retrieving results and responses from save and delete ops to name a few.

JSON Response.

{
  "success": true,
  "message": "User deleted successfully",
  "data": [... optional data if any]
}

ActionResponse

Property	Type	Availability	Description
success	boolean	mandatory	To flag whether a transaction succeeded or failed
message	string	mandatory	The message being send from the server.
data	T (generic)	optional	The extra data you can send with for the transaction.

Example.

saveProfile(data: object): Observable<ActionResponse>{
    return this.http.post<ActionResponse>(url, data)
}

Error Response

Used mainly to process and render errors sent back by the server.

JSON Response.

{
    "exception": "Illuminate\\Validation\\ValidationException",
    "statusCode": 422,
    "message": "The password field is required."
}

ErrorResponse

Property	Type	Availability	Description
exception	string	mandatory	Helps the backend developer to figure the kind of error the API is giving
statusCode	number	mandatory	The status code emitted by the failed API call.
message	string	mandatory	The message emitted by the failed API call

Example usage is when you are creating an API error message handler.

login(credentials: object): Observable<ActionResponse>{
    return this.http.post<ActionResponse>(url, credentials)
        .pipe(catchError(error => {
          const serverError: ErrorResponse = error.error
          throwError(serverError)
    }))
}

The consumer of the error will work with the error in this format.

Auth Response

Used mainly when you are authenticating users especially login and you wanna save the user details on a successful login.

JSON Response.

{
  "user": {
    "id": 1,
    "user_name": "admin",
    "first_name": "Wendell",
    "last_name": "Halvorson",
    "email": "stoltenberg.meghan@example.org",
    "age": 30,
    "salary": 777084
  },
  "token": {
    "access_token": "access token",
    "expires_in": 7200,
    "type": "bearer"
  }
}

AuthResponse

Property	Type	Availability	Description
user	T (generic)	mandatory	The user object brought from a successful login.
token	JWToken	mandatory	The auth token from a success model.

Collection Response

Used when pulling collections of data

• Usually from Model::get() method

  JSON Response.

{
  "data": [
    {
      "id": 40,
      "user_name": "odell80",
      "first_name": "Rhiannon",
      "last_name": "Brakus",
    }, 
    {
      "id": 41,
      "user_name": "flash",
      "first_name": "Ruben",
      "last_name": "Sikes",
    }
  ]
}

CollectionResponse

Paginated Response

Used for mapping paginated results from the API.

JSON Response.

{
    "data": [
        {
            "id": 40,
            "user_name": "odell80",
            "first_name": "Rhiannon",
        },
        {
            "id": 61,
            "user_name": "ykessler",
        }
    ],
    "links": {
        "first": "http://localhost:8000/api/users?page=1",
        "last": "http://localhost:8000/api/users?page=5",
        "prev": null,
        "next": "http://localhost:8000/api/users?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "path": "http://localhost:8000/api/users",
        "per_page": 20,
        "to": 20,
        "total": 99
    }
}

PaginatedResponse

Property	Type	Availability	Description
data	T[] (generic)	mandatory	The collection of objects of type T
links	Links	mandatory	The links of the paginated data.
meta	Meta	mandatory	The meta data of the paginated data.