This web page is under construction.
Abstract
Following API calls handle any interactions within the building information model itself. In order to support multi tenancy in a proper way additional URL paths are to be used containing the team name and the project name.
The team name and the project name need to be specified and setup as so-called slugs to present a clean URL. Slugs are lowercase unique identifiers based on English characters and numbers.
The team slug will be used to know which tenant database to work on.
The project slug is necessary to verify the user's access rights on the project in an early stage of processing the API call – preferably before any business data will be touched and any business logic will be executed.
The JSON objects used for input and output will be based on the IFC standard in terms of structure and naming. First of all it's necessary to have a pure API bound object model and second using a standard based approach.
Representational State Transfer (REST)
Representational State Transfer (REST) is a style of software architecture for distributed systems such as the World Wide Web. REST has emerged as a predominant web API design model.
REST-style architectures consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of representations of resources. A resource can be essentially any coherent and meaningful concept that may be addressed. A representation of a resource is typically a document that captures the current or intended state of a resource.
The client begins sending requests when it is ready to make the transition to a new state. While one or more requests are outstanding, the client is considered in transition. The representation of each application state contains links that may be used the next time the client chooses to initiate a new state-transition.
Key goals of REST:
- Scalability of component interactions
- Generality of interfaces
- Independent deployment of components
- Intermediary components to reduce latency, enforce security and encapsulate legacy systems
REST's client-server separation of concerns simplifies component implementation, reduces the complexity of connector semantics, improves the effectiveness of performance tuning, and increases the scalability of pure server components. Layered system constraints allow intermediary proxies, gateways, and firewalls to be introduced at various points in the communication without changing the interfaces between components, thus allowing them to assist in communication translation or improve performance via large-scale, shared caching. REST lets intermediate processing by constraining messages be self-descriptive: interaction is stateless between requests, standard methods and media types are used to indicate semantics and exchange information, and responses explicitly indicate cacheability.
RESTful architecture constraints
- Client-server separation: no data storage on the client, client and server can be developed independently;
- Stateless: no client context being stored on the server. Each request contains all necessary information to service the request;
- Cacheable: clients can cache responses;
- Layered system: a client doesn'n know if it is directly connected to the server;
- Uniform interface between clients and servers.
- Code on demand (optional): servers can change functionality of a client by the transfer of executable code.[1]
Database operations and HTTP calls
Full use of HTTP methods considered as RESTful. There are four types of the database operation defined for content manipulation: Create, Read, Update, Delete (CRUD). Following HTTP methods implement these operations on persistent level[2]:
Operation |
SQL |
HTTP |
|---|---|---|
Create |
INSERT |
POST |
Read |
SELECT |
GET |
Update |
UPDATE |
PUT |
Delete |
DELETE |
DELETE |
RESTful web API call structure
All necessary information for resource manipulation will be sent within a HTTP request. It includes
- Resource identificator (URL)
- Data type / format (HTTP header)
- Authentication information (HTTP header)
- Operation, which should be performed with the resource (HTTP method)
Media type for the data base operations and client-server communications is JSON.[3]
Client request example:
Service available !
GET
Resource: projects
URL: https://api.bimplus.net/v2/<team>/projects
Example: https://api.bimplus.net/v2/bimplus/projects
Gets the available project list with main properties.
Authorization: BimPlus 9c1874a62c974dcfa75e0132c423a088 Content-Type: application/json
Status: 200 OK
