Building a service provider

Start with: https://github.com/opensourceBIM/BIM-Bot-services/wiki

HTTP

A service provider should be able to accept HTTP requests.

List of services

Your server should be able to generate a list of services that can be provided. You can make up your own URL pattern for this. This is the URL you want to publish when releasing your services. You can for example have this URL added to https://github.com/opensourceBIM/BIMserver-Repository/blob/master/serviceproviders.json. This way anyone using BIMserver will automatically also see your services.

The default URL for this is [server address]/servicelist. The structure of the JSON returned is like this:

{  
   "services":[  
      {  
         "id":4718646,
         "name":"Simple Analyses Service",
         "description":"BIMserver plugin that provides an analysis of a model and and outputs it into json",
         "provider":"Experimental BIMserver",
         "providerIcon":"/img/bimserver.png",
         "inputs":[  
            "IFC_STEP_2X3TC1"
         ],
         "outputs":[  
            "UNSTRUCTURED_UTF8_TEXT_1_0"
         ],
         "oauth":{  
            "authorizationUrl":"https://thisisanexperimentalserver.com/oauth/authorize",
            "registerUrl":"https://thisisanexperimentalserver.com/oauth/register",
            "tokenUrl":"https://thisisanexperimentalserver.com/oauth/access"
         },
         "resourceUrl":"https://thisisanexperimentalserver.com/services"
      }
  ]
}

The id is a unique identifier identifying the service. In this case it's a BIMserver OID, but it can be anything. name, description, provider and providerIcon should speak for themselves.

The inputs array describes the input types this service is able to handle. The outputs array describes which output formats it is able output. The registerUrl, authorizationUrl and tokenUrl are used for OAuth (described later in this document). A list of input/output types can be found here https://github.com/opensourceBIM/BIMserver/wiki/New-remote-service-interface#schemas

resourceUrl is the actual URL the data will be sent to whenever someone wants to invoke the service.

Authentication

See https://github.com/opensourceBIM/BIM-Bot-services/wiki/OAuth

Using the resource

At a certain point, A will trigger B. This can be triggered manually by a user, or automatically as a response to a newly uploaded revision for example. A will send a HTTP POST request to B (resourceUrl/id in the JSON). This POST request should have a HTTP header:

Authorization: Bearer [access_token] (only when using OAuth)
Input-Type: [The selected input type]
Output-Type: [The selected output type]

This header tells B that A will be authorized as user X. The request body should contain the data A wants to send to B. The format of this data can be anything, but it should be negotiated earlier. B will keep the HTTP request open until it is reading processing the data. B will then put the resulting data in the POST response body. A will then usually store this data (as extended data on BIMserver).

Extra HTTP response header fields that will be processed when available:

Content-Disposition (for example 'attachment; filename="[filename]"')
Content-Type (for example: "application/json")
Output-Type (see https://github.com/opensourceBIM/BIMserver/wiki/New-remote-service-interface#schemas)
Data-Title (when used, this will be the title of the extended data, or the comment of a new revision in BIMserver)

Examples

Full request:

HTTP Request Header

POST /services/returnifc.php HTTP/1.1
Authorization: Bearer 4c93d2755e8aa69270eb5a1333e8b7b35969e325
Content-Length: 2809608  
Host: test.logic-labs.nl
Connection: Keep-Alive  
User-Agent: Apache-HttpClient/4.5.1 (Java/1.8.0_101)
Accept-Encoding: gzip,deflate 
Input-Type: IFC_STEP_2X3TC1
Output-Type: VALIDATION_JSON_1_0

HTTP Request Body

ISO-10303-21;
HEADER;
FILE_DESCRIPTION ((''), '2;1');
FILE_NAME ('', '2017-05-03T11:13:21', (''), (''), '', 'BIMserver', '');
FILE_SCHEMA (('IFC2X3'));
ENDSEC;
DATA;
#1= IFCPROPERTYSINGLEVALUE('ConstructionMode',$,IFCLABEL('Massivbau'),$);
#2= IFCPROPERTYSINGLEVALUE('BuildingPermitId',$,IFCIDENTIFIER('4711'),$);
#3= IFCPROPERTYSINGLEVALUE('GrossAreaPlanned',$,IFCAREAMEASURE(1000.),$);
...
ENDSEC;
END-ISO-10303-21;

HTTP Response Header

HTTP/1.1 200 OK
Server: nginx/1.10.0 (Ubuntu)
Date: Wed, 03 May 2017 10:05:16 GMT
Content-Type: application/ifc
Content-Length: 280191
Connection: keep-alive
Set-Cookie: PHPSESSID=5u98is6n313fnpkosoodgobcn5; path=/
Expires: 0
Cache-Control: must-revalidate
Pragma: public
Content-Description: File Transfer
Content-Disposition: attachment; filename="validationresults.json"

HTTP Response Body

{  
   "items":[  
      {  
         "type":"header",
         "text":"PROJECT"
      },
      {  
         "type":"line",
         "status":"SUCCESS",
         "oid":-1,
         "identification":"Number of projects",
         "value":"1 projects",
         "shouldBe":"Exactly 1 IfcProject objec
...