# @kernel-js/api

## @kernel-js/api

[![Build Status](https://travis-ci.org/kernel-js/api.svg?branch=develop)](https://travis-ci.org/kernel-js/api) [![Coverage Status](https://coveralls.io/repos/github/kernel-js/API/badge.svg?branch=master)](https://coveralls.io/github/kernel-js/API?branch=master) \


> Package to easily develop REST API following JSON API specification.

### Why

First of all I created this to support development of [Kernel Framework](https://www.npmjs.com/package/@kernel-js/framework).\
&#x20;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](https://app.gitbook.com/s/-LY2LZBI-06hbxomgLJf/api/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.

```javascript
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.

```javascript
export default class Post extends Entity{

    resourceName() {
      return 'posts';
    }

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

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

}
```

###

## All

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

## /api/posts

<mark style="color:blue;">`GET`</mark> `https://api.kernel.com/v1/api/posts`

This endpoint allows you to get posts.

{% tabs %}
{% tab title="200 Post successfully retrieved." %}
```javascript
{
    "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"
            }
        },
    ]
}
```
{% endtab %}
{% endtabs %}

## Find

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

## /api/posts/1

<mark style="color:blue;">`GET`</mark> `https://api.kernel.com/v1/api/posts/1`

{% tabs %}
{% tab title="200 " %}
```
{
    "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"
            }
        },
    ]
}
```
{% endtab %}
{% endtabs %}

## Paginate

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

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

<mark style="color:blue;">`GET`</mark> `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 |

{% tabs %}
{% tab title="200 " %}
```
{
    "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"
    }
}
```
{% endtab %}
{% endtabs %}

## Save

```typescript
// 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

<mark style="color:green;">`POST`</mark> `https://api.kernel.com/api/posts`

{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}

### Update

## /api/posts/1

<mark style="color:orange;">`PUT`</mark> `https://api.kernel.com/api/posts/1`

{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}

## Delete

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

## /api/posts

<mark style="color:red;">`DELETE`</mark> `https://api.kernel.com/api/posts/1`

{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}

### With

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

## /api/posts/1

<mark style="color:blue;">`GET`</mark> `https://api.kernel.com/api/posts/1?include=tags,author`

#### Path Parameters

| Name    | Type   | Description                    |
| ------- | ------ | ------------------------------ |
| include | string | Relacionamento entre entidades |

{% tabs %}
{% tab title="200 " %}
```
{
    "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"
            }
        }
    ]
}
```
{% endtab %}
{% endtabs %}

### Authors

This library was developed by

* Carlos Henrique Escouto
* Gustavo Siqueira
* Bruno Santos



### Contribute

Please do! Check out our [Contributing guidelines](https://app.gitbook.com/s/-LY2LZBI-06hbxomgLJf/api/CONTRIBUTING.md).

### License

[MIT](https://app.gitbook.com/s/-LY2LZBI-06hbxomgLJf/api/LICENSE) © 2018-2018 Kernel JS
