> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superoffice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure SuperOffice REST WebAPI

> Describes how to setup and enable NetServer REST services in IIS.

SuperOffice REST WebAPI services are available from version 8.1.

## Introduction

**Representational State Transfer** (REST) is an architectural pattern penned by Roy Fielding for creating an HTTP-based API. There's no shortage of articles online that discuss what REST is, how it's been interpreted and how it's been implemented on various platforms. That will not be discussed here. This section will focus primarily on how to setup SuperOffice REST in IIS and perform a simple test.

## Configuration

Before any request are sent to the web server, NetServer must be configured to support REST requests and IIS must be configured to handle all of the HTTP verbs.

### Configure NetServer

In the current SuperOffice installations, NetServer REST services are switched on by default and may not need to be configured. However, for the sake of knowledge, these settings are a feature that must be toggled on by adding or changing the settings in the configuration file.

Ensure the following entries in SuperOffice sectionGroup element: the [WebApi section][1].

**SuperOffice sectionGroup in web.config:**

```xml theme={null}
<sectionGroup name="SuperOffice">
  <section name="WebApi" type="System.Configuration.NameValueSectionHandler, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
</sectionGroup>
```

Locate or add the `WebApi` element and set one or both keys to true to enable: `AuthorizeWithUsername` and `AuthorizeWithTicket`.

**SuperOffice element in web.config:**

```xml theme={null}
<SuperOffice>
  <WebApi>
    <add key="AuthorizeWithUsername" value="true" />
    <add key="AuthorizeWithTicket" value="true" />
  </WebApi>
</SuperOffice>
```

Now that the NetServer configuration is complete, let's configure IIS.

### Configure HTTP Action Verbs (IIS)

In IIS, navigate to the SuperOffice web client application, or NetServer if installed standalone, and select it. Then, in \*\***Features View**, double-click **Handler Mappings**.

In the Handler Mappings view, locate and double-click the **ExtensionlessUrlHandler-Integrated-4.0** list item. The **Edit Managed Handler** dialog will appear. Click the **Request Restrictions** button in the Edit Managed Handler dialog to open the Request Restrictions dialog.

Click to view the **Verbs** tab in the Request Restrictions dialog. Next click the **All Verbs** option, then click **OK** to close the dialog. Close the remaining dialogs and close to exit the IIS manager.

![iis-configuration][img1]

**IIS Manager Handler Mappings:**

![IIS Manager Handler Mappings -screenshot][img1]

IIS is now configured to access and process all request verbs, and therefore permit requests to create, read, update and delete via SuperOffice REST APIs.

### Configure Basic Authentication (IIS)

While API authentication is discussed below, it's important to understand how to configure IIS if you plan on using basic authentication.

To enable Basic Authentication for REST API, first enable basic authentication on the website root. Do this by selecting the root website, then double-click the Authentication icon in the **Features View** pane. With the **Authentication** panel shown, right-click the **Basic Authentication** option and set the status to Enabled.

![Enable basic authentication on the website root -screenshot][img2]

Next, disable Basic Authentication on the SuperOffice web application. Select the SuperOffice web application under the root website, then double-click the Authentication icon. In the **Authentication** panel, if the Basic Authentication status is *Enabled*, right-click Basic Authentication and select *Disable*.

![Disable basic authentication on the SuperOffice web application -screenshot][img3]

With Basic Authentication configured this way, any valid SuperOffice user can navigate to the REST URLs and invoke a request. To test these settings, navigate to the application's URL and attempt to get the contact where contact ID equals 1. Do that by navigating in a browser to `http://superoffice80/api/v1/contact/1` and this should result in a **Credentials** dialog prompting for a username and password. Any valid SuperOffice username works.

## Integrated with Active Directory

### SuperOffice Users

To integrate with Active Directory, you need to set up your SuperOffice users as Active Directory users.

* *web.config* must define and configure the [ActiveDirectoryCredentialPlugin section][5].
* SuperOffice users must be linked to Active Directory users.

### SuperOffice web.config

You must explicitly [enable the authentication methods][1] you want to use in the *web.config* file.

```XML theme={null}
<WebApi>
  <add key="AuthorizeWithImplicit" value="true" />
</WebApi>
```

<Note>
  `AuthorizeWithImplicit` must be **true**; otherwise, the Active Directory authentication method will not work. It adds the `WWW-Authenticate: Negotiate` header that kicks off Windows authentication.
</Note>

### IIS configuration

1. Open the IIS Configuration tool and select the SuperOffice application.

2. In IIS, navigate to the application hosting SuperOffice web client.

3. Enable Windows Authentication, and disable the others.

   ![iis-authentication-windows -screenshot][img17]

4. Click **Advanced Settings** to enable Kernel-mode authentication.

   ![iis-kernel-mode-auth -screenshot][img18]

5. Click **Providers** to ensure that **Negotiate** is the first enabled provider.

   ![iis-auth-providers -screenshot][img19]

Your SuperOffice and WebAPI are now accessible without logging in.

The HTTP.sys kernel driver will stop unauthenticated requests before they reach ASP.net and send back an ActiveDirectory response that the browser can use to log in using its windows identity.

Accessing `/api/v1/user/currentPrincipal` via Chrome or Edge should automatically log you in, and return the current user's info.

## Hello WebAPI

So now we can make our first request to the API endpoint:

```http theme={null}
GET https://{{superoffice_url}}/api
Accept: application/json; charset=utf-8
```

This will request the API overview. If you use a browser to open `http://crm.example.com/superoffice/api` you will get a webpage that says:

```http theme={null}
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
Content-Encoding: gzip
Expires: -1
Vary: Accept-Encoding
Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
Date: {todays date}

{
  "v1": "{{superoffice_url}}/api/v1/",
  "NetServerVersion": "{current_version}",
  "NetServerAssembly": "{current_assembly_version}",
  "NetServerDate": "{build_date}",
  "NetServerLabel": "{build_release_version}",
  "NetServer": "SuperOffice {version} NetServer {version info}",
  "Services": "Services??",
  "ServicesCurrent": "Services??",
  "Version": "v1"
}
```

If you use [POSTMAN][2] or a similar tool, you will get back some JSON that contains the same information instead of an HTML page.

This gets us some metadata about the API without logging in, and an indication that the API is up and running correctly.

## Conclusion

SuperOffice REST services add another API surface to the NetServer real estate. To learn more about SuperOffice REST services, see the \[web services APIs].

[1]: ../../web-config/webapi

[2]: https://www.getpostman.com/

[5]: ../../web-config/security

[img1]: /media/loc/en/onsite/iis-configuration.png

[img2]: /media/loc/en/onsite/websiteauthentication.png

[img3]: /media/loc/en/onsite/soapplicationauthentication.png

[img17]: /media/loc/en/onsite/iis-authentication-windows.png

[img18]: /media/loc/en/onsite/iis-kernel-mode-auth.png

[img19]: /media/loc/en/onsite/iis-auth-providers.png


## Related topics

- [Configure Basic Authentication in IIS](/en/onsite/install/netserver/enable-basic-auth.md)
- [SuperOffice.WebApi.Data.UserPreferenceStrings.DataCollection](/en/api/reference/webapi/SuperOffice.WebApi.Data.UserPreferenceStrings.DataCollection.md)
- [How to configure settings in SuperOffice Settings and maintenance](/integrations/sharepoint-documents/configure-superoffice.md)
- [Install and configure ModSecurity on proxy server](/en/onsite/security/set-up-modsecurity.md)
- [SuperOffice.WebApi.Agents.WorkflowAgent](/en/api/reference/webapi/SuperOffice.WebApi.Agents.WorkflowAgent.md)
- [SuperOffice.WebApi.Agents.TargetsAgent](/en/api/reference/webapi/SuperOffice.WebApi.Agents.TargetsAgent.md)