Nefarious Pickle Muncher

    This package has been deprecated

    Author message:

    this package has been deprecated

    @andrewfarinella/mapi

    0.2.2 • Public • Published

    mapi

    Build Status Coveralls github branch npm version


    A simple RESTful API interface.

    Install

    NPM

    $ npm install @andrewfarinella/mapi --save

    Yarn

    $ yarn add @andrewfarinella/mapi

    Example

    import Mapi from '@andrewfarinella/mapi'
    
    const api = new Mapi({
        base: 'http://localhost:8080',
        services: [ 'posts' ]
    });
    
    api.posts.get(1)
        .then(response => {
            // Do whatever...
        }).catch(err => {
            // Handle error...
        })

    Usage

    Import

    import mapi from '@andrewfarinella/mapi'
    
    // or
    
    mapi = require('@andrewfarinella/mapi')

    mapi setup

    const api = mapi({
        base: 'http://localhost:8080',
        headers: [
            ['Authorization', 'MyKeyHere']
        ],
        services: [
            {
                name: 'posts',
                base: '/different-base'
            },
            'comments'
        ]
    })

    Service setup

    Services can be registered either at setup or afterwards using the mapi.registerService() method.

    The only required property is name. If base is not supplied, the base will be generated based on the name property.

    api = mapi({base: 'http://localhost:8080'})
    
    api.registerService({
      name: 'posts',
        base: '/posts',
        defaultEndpoints: true,
        hasHealthCheck: true,
        healthCheck: {
          method: 'GET',
          endpoint: '/health',
          hasBody: false,
          requiresAuth: false,
          alias: 'health'
        },
        endpoints: [
          {
            method: 'GET',
            endpoint: '/:id?',
            hasParams: true,
            hasBody: false,
            requiresAuth: true,
            alias: 'get'
          },
          {
            method: 'POST',
            endpoint: '/',
            hasParams: false,
            hasBody: true,
            requiresAuth: true,
            alias: 'create'
          },
          {
            method: 'PUT',
            endpoint: '/:id',
            hasParams: true,
            hasBody: true,
            requiresAuth: true,
            alias: 'update'
          },
          {
            method: 'DELETE',
            endpoint: '/:id',
            hasParams: true,
            hasBody: false,
            requiresAuth: true,
            alias: 'delete'
          }
        ],
        services: [
          {
            name: 'new' // Builds to /posts/new
          }
        ]
    })

    Endpoint setup

    Endpoints can be registered when a service is registered or by calling service.registerEndpoint().

    While the only required field for endpoints is alias, the endpoint URL will not auto-generate based on the alias property, but instead will default to '/'. This may have unintended side-effects, so it's recommended that an endpoint property always be supplied as well.

    api = mapi({base: 'http://localhost:8080', services: ['posts']})
    
    api.posts.registerEndpoint({
      method: 'GET',
      endpoint: '/:id',
      hasParams: true,
      params: [
        {
          slug: 'id',
          pattern: ':id',
          required: true
        }
      ]
      hasBody: false,
      alias: 'get'
    })

    If no parameters are listed but hasParams is set to true and there is at least one : in the endpoint, mapi will attempt to discover the parameters automatically. If a parameter is not required, it can be indicated by ending it with ? such as /:id?.

    Making Calls

    When making a call to a registered endpoint, the number of arguments expected depends on the hasParams and hasBody properties.

    // hasParams === false && hasBody === false
    api.posts.get()
      .then((response => {})).catch(err => {})
    
    // hasParams === true && hasBody === false
    api.posts.get(params)
      .then((response => {})).catch(err => {})
    
    // hasParams === false &&& hasBody === true
    api.posts.create(body)
      .then((response => {})).catch(err => {})
    
    // hasParams === true &&& hasBody === true
    api.posts.update(params, body)
      .then((response => {})).catch(err => {})

    Parameters can be passed to the call as either a string, integer, or an object.

    // Endpoint has only one parameter, so we can pass it a string/integer
    
    // /posts/:id
    api.posts.get(1) // /posts/1
    
    // /posts/:slug
    api.posts.get('my-post-slug') // /posts/my-post-slug
    
    // Parameters can also be passed within an object
    
    // /posts/:id/comments/:commentId
    api.posts.getComments({
      id: 1,
      commentId: 3
    })

    Keywords

    Install

    npm i @andrewfarinella/mapi

    DownloadsWeekly Downloads

    0

    Version

    0.2.2

    License

    MIT

    Unpacked Size

    233 kB

    Total Files

    17

    Last publish

    Collaborators

    • andrewfarinella