Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/intjelic/byteplug-endpoints

A HTTP client for Node.js to work with Byteplug endpoints easily.
https://github.com/intjelic/byteplug-endpoints

byteplug endpoints http-client javascript nodejs

Last synced: about 11 hours ago
JSON representation

A HTTP client for Node.js to work with Byteplug endpoints easily.

Awesome Lists containing this project

README 

        
# Byteplug Endpoints (WIP!)



This is a HTTP client for Node.js to interact with HTTP APIs implementing the

Endpoints standard from Byteplug. It's essentially a wrapper around **axios**

to expose an easier-to-work-with interface. Therefore, this library works (in

theory) on both the browser and node.



```bash

npm install byteplug-endpoints

```



```javascript

import Endpoints from 'byteplug-endpoints'



var endpoints = new Endpoints("http://api.my-company.com")



var endpoint = endpoints.endpoint("foo")

endpoint.response = function(document) {

    // Do something with response and its document.

}



const document = {

    foo: "bar",

    bar: "foo"

}

endpoint.request(document)

```



This project is a **work-in-progress** and its API is subject to change

drastically (it's mostly for internal use so far).



## How to use



There is no documentation at the moment and this section is the only source of

information.



You must first create a global `Endpoints` object with the base URL. Note that

on a Vue.js app, this is typically shared across all components as a global

property.



```javascript

var endpoints = new Endpoints("https://api.my-company.com")

```



To interact with an endpoint, you must first create an endpoint object with

either `endpoint()` or `collectionEndpoint()`.



```javascript

var nonCollectionEndpoint = endpoints.endpoint("my-path")

var collectionEndpoint = endpoints.collectionEndpoint("my-collection", "my-path", false)

var itemCollectionEndpoint = endpoints.collectionEndpoint("my-collection", "my-path", true)

```



Then you attach the response and error handlers to this endpoint object. It

also supports `clientError` and `serverError`.



```javascript

myEndpoint.response = (document) => {

    //

}

myEndpoint.errors['foo'] = (document) -=> {

    // Deal when 'foo' error is returned.

}

myEndpoint.errors['bar'] = () -=> {

    // Deal when 'bar error is returned'

}

```



At this point, no HTTP request has been made yet, you must call the `request()`

method with the document, if any, and a token.



```javascript

myEndpoint.request(document/*, token*/)

```



If the endpoint requires authentication, pass the token after the document. If

the endpoint operates on an item of a collection, you must pass the item ID as

well. For instance:



```javascript

item = "42"

myCollectionEndpoint.request(item, document, token)

```



The `request()` method returns a promise, and therefore you can wait for the

HTTP request to actually be completed and wait until all callbacks are

fully run.



## Additional notes



This HTTP client expects a compliant behavior from the server. When it finds

oddities, the promise returned by `request()` will fail with an explicit

message error.



It also implements very basic unit tests (it's far from being complete).



```

npm run test

```

```

> [email protected] test

> ava



  ✔ client-side-error

  ✔ server-side-error

  ✔ non-collection-endpoint

  ✔ collection-endpoint-without-item

  ✔ authorization-token

  ✔ collection-endpoint-with-item

  ✔ non-compliant-endpoints

  ✔ timeout-error (209ms)

  ─



  8 tests passed

  ```