@kernel-js/api

Package to easily develop REST API following JSON API specification.

Why

First of all I created this to support development of Kernel Framework. Just like the rest of the packages that make up the framework, I make the most of other existing libraries that are well tested on a day-to-day basis. The idea is not to reinvent the wheel, just join the ideas in a lightweight framework (the focus is on the client side), simple to use and make the code on the front more beautiful and organized.

Install

npm install @kernel-js/api

Class Directory

Common Class

EntityManager

Common Triggers Methods

getEntity
getContent
getUrl
getUrlConfig

Common Request Methods

all
find
search*
save
delete
attach
detach
createPivot
deletePivot

Common Fetching Methods

with
select
orderByAsc
orderByDesc
where
limit

Building Classes

Base Entity Class

É necessário criar uma classe que herdará e sobrescreverá os métodos dessa classe dentro da sua aplicação Essa mesma classe vai ser herdada pelas entidades da aplicação.

export default class Entity extends EntityManager {

  async request (config) {
    return Axios.request(config); // Você retornará a instancia do axios na sua aplicação
  }

  baseUrl() {
    return 'http://127.0.0.1:8000/api'
  }

}

Aplication Entity Class

Você sobrescreverá os métodos de Entity na sua aplication-entity (user) informando os dados e relacionamentos da mesma.

export default class Post extends Entity{

    resourceName() {
      return 'posts';
    }

    fields() {
      return ['title', 'slug', 'subtitle', 'body'];
    }

    relationshipNames() {
      return ['tags', 'author'];
    }

}

All

let post: Post = new Post();
let posts: Array<Post> = post.all().getEntity();

/api/posts

GET https://api.kernel.com/v1/api/posts

This endpoint allows you to get posts.

{
    "data": [
        {
            "type": "posts",
            "id": "1",
            "attributes": {
                "slug": "ut-ut-similique-et-cumque-laboriosam-occaecati",
                "title": "Ut ut similique et cumque laboriosam occaecati.",
                "subtitle": "Eos enim impedit neque libero nihil molestiae aspernatur atque. Numquam temporibus quia omnis ut.",
                "body": "Sunt sit ut doloremque voluptas. Iusto omnis labore illum id.\n\nExercitationem dolor quae ullam et id a. Architecto repellendus saepe odio. Voluptates accusantium ut doloremque suscipit. Vel velit cumque omnis sed.\n\nMaiores voluptates soluta aut qui praesentium. Ab modi voluptas porro animi. Perspiciatis occaecati qui quo dignissimos et. Autem repudiandae dolorem rem nesciunt.",
                "published_at": "2019-06-26"
            },
            "links": {
                "self": "/api/posts/1"
            }
        },
        {
            "type": "posts",
            "id": "2",
            "attributes": {
                "slug": "totam-laboriosam-cupiditate-cupiditate-repudiandae-est-aut-dolores",
                "title": "Totam laboriosam cupiditate cupiditate repudiandae est aut dolores.",
                "subtitle": "Aperiam ut et sequi perspiciatis. Quasi aut porro voluptatem distinctio nihil.",
                "body": "Sit atque deleniti explicabo placeat. Distinctio omnis possimus explicabo minus similique vitae. Ut culpa officia et fugit libero totam. Et repellat ducimus ipsa impedit placeat. Consectetur reprehenderit qui reiciendis.\n\nExpedita aliquid nobis est praesentium fuga quia. Ut dolores tempora quidem sunt ea.\n\nTempore consequatur quis pariatur non tempore eum. Dolorem dignissimos impedit possimus dolorem ad id. Eum voluptatem dolor voluptate voluptatem.",
                "published_at": "2019-06-25"
            },
            "links": {
                "self": "/api/posts/2"
            }
        },
    ]
}

Find

let post: Post = new Post();
post = post.find(1).getEntity();

/api/posts/1

GET https://api.kernel.com/v1/api/posts/1

{
    "data": [
        {
            "type": "posts",
            "id": "1",
            "attributes": {
                "slug": "ut-ut-similique-et-cumque-laboriosam-occaecati",
                "title": "Ut ut similique et cumque laboriosam occaecati.",
                "subtitle": "Eos enim impedit neque libero nihil molestiae aspernatur atque. Numquam temporibus quia omnis ut.",
                "body": "Sunt sit ut doloremque voluptas. Iusto omnis labore illum id.\n\nExercitationem dolor quae ullam et id a. Architecto repellendus saepe odio. Voluptates accusantium ut doloremque suscipit. Vel velit cumque omnis sed.\n\nMaiores voluptates soluta aut qui praesentium. Ab modi voluptas porro animi. Perspiciatis occaecati qui quo dignissimos et. Autem repudiandae dolorem rem nesciunt.",
                "published_at": "2019-06-26"
            },
            "links": {
                "self": "/api/posts/1"
            }
        },
    ]
}

Paginate

let post: Post = new Post();
let posts: Array<Post> = post.paginate(5, 1).all().getEntity();

/api/posts?page[size]=5&page[number]=1

GET https://api.kernel.com/api/posts?page[size]=5&page[number]=1

Path Parameters

Name

Type

Description

page[size]

string

Quantos registros por pagina

Query Parameters

Name

Type

Description

page[number]

string

Pagina atual

{
    "data": [
        {
            "type": "posts",
            "id": "1",
            "attributes": {
                "slug": "ut-ut-similique-et-cumque-laboriosam-occaecati",
                "title": "Ut ut similique et cumque laboriosam occaecati.",
                "subtitle": "Eos enim impedit neque libero nihil molestiae aspernatur atque. Numquam temporibus quia omnis ut.",
                "body": "Sunt sit ut doloremque voluptas. Iusto omnis labore illum id.\n\nExercitationem dolor quae ullam et id a. Architecto repellendus saepe odio. Voluptates accusantium ut doloremque suscipit. Vel velit cumque omnis sed.\n\nMaiores voluptates soluta aut qui praesentium. Ab modi voluptas porro animi. Perspiciatis occaecati qui quo dignissimos et. Autem repudiandae dolorem rem nesciunt.",
                "published_at": "2019-06-26"
            },
            "links": {
                "self": "/api/posts/1"
            }
        },
        {
            "type": "posts",
            "id": "2",
            "attributes": {
                "slug": "totam-laboriosam-cupiditate-cupiditate-repudiandae-est-aut-dolores",
                "title": "Totam laboriosam cupiditate cupiditate repudiandae est aut dolores.",
                "subtitle": "Aperiam ut et sequi perspiciatis. Quasi aut porro voluptatem distinctio nihil.",
                "body": "Sit atque deleniti explicabo placeat. Distinctio omnis possimus explicabo minus similique vitae. Ut culpa officia et fugit libero totam. Et repellat ducimus ipsa impedit placeat. Consectetur reprehenderit qui reiciendis.\n\nExpedita aliquid nobis est praesentium fuga quia. Ut dolores tempora quidem sunt ea.\n\nTempore consequatur quis pariatur non tempore eum. Dolorem dignissimos impedit possimus dolorem ad id. Eum voluptatem dolor voluptate voluptatem.",
                "published_at": "2019-06-25"
            },
            "links": {
                "self": "/api/posts/2"
            }
        }
    ],
    "meta": {
        "pagination": {
            "total": 10,
            "count": 2,
            "per_page": 2,
            "current_page": 1,
            "total_pages": 5
        }
    },
    "links": {
        "self": "https://api.kernel.com/api/posts?page%5Bsize%5D=2&page%5Bnumber%5D=1",
        "first": "https://api.kernel.com/api/posts?page%5Bsize%5D=2&page%5Bnumber%5D=1",
        "next": "https://api.kernel.com/api/posts?page%5Bsize%5D=2&page%5Bnumber%5D=2",
        "last": "https://api.kernel.com/api/posts?page%5Bsize%5D=2&page%5Bnumber%5D=5"
    }
}

Save

// Create - POST
let newPost: Post = new Post();
newPost.attribute.title = 'Lorem';
newPost.save();

// Edit - PUT
let post : Post = new Post();
post = post.find(1).getEntity();
post.attribute.title = 'Lorem';
post.save();

Create

/api/posts

POST https://api.kernel.com/api/posts

Update

/api/posts/1

PUT https://api.kernel.com/api/posts/1

Delete

let post: Post = new Post();
post = post.find(1).getEntity();
post.delete();

/api/posts

DELETE https://api.kernel.com/api/posts/1

With

let post: Post = new Post();
post = post.with('tags', 'author').find(1).getEntity();

/api/posts/1

GET https://api.kernel.com/api/posts/1?include=tags,author

Path Parameters

Name

Type

Description

include

string

Relacionamento entre entidades

{
    "data": {
        "type": "posts",
        "id": "1",
        "attributes": {
            "slug": "ut-ut-similique-et-cumque-laboriosam-occaecati",
            "title": "Ut ut similique et cumque laboriosam occaecati.",
            "subtitle": "Eos enim impedit neque libero nihil molestiae aspernatur atque. Numquam temporibus quia omnis ut.",
            "body": "Sunt sit ut doloremque voluptas. Iusto omnis labore illum id.\n\nExercitationem dolor quae ullam et id a. Architecto repellendus saepe odio. Voluptates accusantium ut doloremque suscipit. Vel velit cumque omnis sed.\n\nMaiores voluptates soluta aut qui praesentium. Ab modi voluptas porro animi. Perspiciatis occaecati qui quo dignissimos et. Autem repudiandae dolorem rem nesciunt.",
            "published_at": "2019-06-26"
        },
        "links": {
            "self": "/api/posts/1"
        },
        "relationships": {
            "author": {
                "links": {
                    "self": "/api/posts/1/relationships/author",
                    "related": "/api/posts/1/author"
                },
                "data": {
                    "type": "users",
                    "id": "1"
                }
            },
            "tags": {
                "links": {
                    "self": "/api/posts/1/relationships/tags",
                    "related": "/api/posts/1/tags"
                },
                "data": [
                    {
                        "type": "tags",
                        "id": "8"
                    }
                ]
            }
        }
    },
    "included": [
        {
            "type": "users",
            "id": "1",
            "attributes": {
                "name": "Velva Pouros",
                "email": "uschneider@example.net"
            },
            "links": {
                "self": "/api/users/1"
            }
        },
        {
            "type": "tags",
            "id": "8",
            "attributes": {
                "name": "impedit"
            },
            "links": {
                "self": "/api/tags/8"
            }
        }
    ]
}

Authors

This library was developed by

Carlos Henrique Escouto
Gustavo Siqueira
Bruno Santos

Contribute

Please do! Check out our Contributing guidelines.

License

PreviousChange Log

Last updated 6 years ago

Was this helpful?