Prerequisites

Prerequisites#

In order for you to be able to use this API, you need to have:

API-Key

The API-Key is a secret provided by Netfiles GmbH for your use in your application. Please note that the key is assigned on a per-application basis. In all examples, the placeholder for the API-Key is <myAPIKey>

DeviceID

This is the Unique Device ID that you must provide for each machine (Laptop, Desktop, Tablet, Phone) your application is installed on. It must be unique (on iOS, e.g., the best way to generate that ID is using UIDevice.current.identifierForVendor?.uuidString expression in Swift). We will be using <currentDeviceID> as placeholder in the examples below.

Username & User-Password

This is the user’s name (login or e-mail address) and password. We will be using <username> and <password> for this.

Authorization#

Netfiles uses Basic authorization (also known maybe as HTTP-Authorization) for user-login. This may seem insecure but since it is always used only with https it shouldn’t be any problem.

Basics#

All Netfiles API requests consist of the following components:

<Base-URL><Object-Path>;internal&action=mobile.json<API-Key><Device ID><Requested Method>
Base-URL

This is the base-URL for the server. Usually, this is https://app.netfiles.de/

Object-Path

This is the path of the object that you are requesting. Usually, this is just the HW Object ID.

internal&action=mobile.json

This component is fixed and needs to be included as shown.

API-Key

This is the API-Key. It is expressed as &apikey=<myAPIKey>

Device ID

The Unique DeviceID as explained above and expressed as &deviceID=<currentDeviceID>

Requested Method

This the actual function that you are requesting. It is expressed as &method=<requestedMethod>. See Calls Overview for all available request methods that you can send.

The complete Request thus looks like

GET https://app.netfiles.de/<dataroom>/projectfiles/<path>;internal&action=mobile.json&apikey=anApiKey&deviceID=aDeviceID&method=getChildren

The complete request must contain the full Authorization information and the Accept-Header:

GET https://app.netfiles.de/;internal&action=json&apikey=<myAPIKey>&deviceID=<currentDeviceID>&method=checkIdentity
Authorization: Basic BASE64(UTF8Bytes(<username>:<password>))
Accept: application/json

Note: According to how it is implemented in the original iPad-App, the Authorization - Header must be provided with each call.

User Agent#

It is good practice to provide a User-Agent header. In our case, we are using iPad.

Cookies#

With the initial checkIdentity call you will receive a set of cookies using the Set-Cookie-Header. You must keep these cookies and send them back with each request from then on.

Only a checkIdentity-call may not contain these cookies. Next time you make a checkIdentity-call you need to discard the cookies before making the call.

An example of a complete call requesting the list of children of an (given you have the right api-keys) may look like this:

GET https://app.netfiles.de/<dataroom>/projectfiles/<path/to/object>;internal&action=mobile.json&apikey=<myAPIKey>&&deviceID=<currentDeviceID>&method=getChildren
Authorization: Basic BASE64(<username>:<password>)
Accept: application/json
netfiles: <value of the netfiles cookie>
sk1: <value of the sk1 cookie>
HW_User: <value of the HW_User cookie>
HyperwaveSession: <value of the HyperwaveSession cookie>
sk_s_web_S: <value of the sk_s_web_S cookie>
sk_p_web_S: <value of the sk_p_web_S cookie>

Response Headers#

Unfortunately, the Content-Type in the response headers from the server is always application/json, even as response to a Get Content call when the content you receive is something completely different.

You have to retrieve the object’s Hyperwave Record (getObject on the object or getChildren on the parent) and check the documentType there.

On that matter, a .json-file is not identified as application/json but rather application/octet-stream.

So, the guideline is: trust only the documentType in the object’s Hyperwave Record (retrieved either through a call to Get Object or through Get Children of the appropriate parent object) unless:

  1. The object is a file (type == "document") and

  2. Its extension is .json

In this case, you should ignore what is stored in the object-record and assume it is a JSON-file.