Skip to content

Latest commit

 

History

History
161 lines (106 loc) · 3.91 KB

README.md

File metadata and controls

161 lines (106 loc) · 3.91 KB
Raw

sp-rest-proxy - SharePoint REST API Proxy for Node.js and Express local serve

NPM

npm version Downloads

Allows to perform API calls to local Express application with forwarding the queries to a remote SharePoint instance.

This concept was created to show how is could be easy to implements real world data communications for SharePoint Framework local serve mode during web parts debug without deployment to SharePoint tenant.

Supported SharePoint versions

  • SharePoint Online
  • SharePoint 2013
  • SharePoint 2016

Support proxying

  • REST API
  • CSOM requests
  • SOAP web services
  • Static resources

Proxy modes

  • API Proxy server
  • Socket gateway server
  • Socket gateway client

Socket proxying allows to forward API from behind NAT (experimental).

How to use as a module

1. Install NPM module in the project:

npm install --save-dev sp-rest-proxy

or

yarn add sp-rest-proxy --dev

2. Create server.js with the following code:

const RestProxy = require('sp-rest-proxy');

const settings = {
    configPath: './config/private.json', // Location for SharePoint instance mapping and credentials
    port: 8080,                          // Local server port
    staticRoot: './static'               // Root folder for static content
};

const restProxy = new RestProxy(settings);
restProxy.serve();

Configuration parameters cheatsheet

3. Add npm task for serve into package.json:

"scripts": {
    "serve": "node ./server.js"
}

Check if the path to server.js is correct.

4. Run npm run serve.

5. Provide SharePoint configuration parameters.

6. Test local API proxy in action.

How to develop

Install

1. Clone/fork the project:

git clone https://github.com/koltyakov/sp-rest-proxy

2. CMD to the project folder.

3. Install dependencies:

npm install

or

yarn install

4. Build:

npm run build

5. Run the server:

npm run serve

or serve in TypeScript directly

npm run ts-serve

Prompts credentials for a SharePoint site.

6. Navigate to http://localhost:8080 (or whatever in settings)

7. Ajax REST calls as if you were in SharePoint site page context:

REST Client Example

8. Tests.

npm run test

Tests Example

Authentication settings

The proxy provides wizard-like approach for building and managing config files for node-sp-auth (Node.js to SharePoint unattended http authentication).

  • SharePoint 2013, 2016:
    • Addin only permissions
    • User credentials through the http ntlm handshake
    • Form-based authentication (FBA)
  • SharePoint Online:
    • Addin only permissions
    • SAML based with user credentials
    • ADFS user credentials (works with both SharePoint on-premise and Online)

For more information please check node-sp-auth credential options and wiki pages. Auth settings are stored inside ./config/private.json.

Some additional info

sp-rest-proxy works with PnP JS Core (not POST request, as there is an endpoint transformation during POST request in PnP JS Core):

PnP JS Core + sp-rest-proxy

Use cases

  • Client side applications development with local serve, but real data from SharePoint
  • SharePoint Framework in local workbench with real data
  • Client applications integration test automation scenarios