Guide, CoClass

License

A license must be purchased by contacting the CoClass team. Contact us at coclass@byggtjanst.se please.

Before you start using the CoClass API you need basic API knowledge, and an account at https://developer.byggtjanst.io.  

API introduction

API is and abbreviation of “Application Programming Interface”. The purpose of an API is to enable a developer to access resources from an application, by providing a programmable interface.

  • One of the most common API types is “REST”. This is an API architecture intended for being used on the internet

  • A typical application resource is an object containing data

An API interface usually consists of:

  • A client application: This is from where an API “Request” is sent

  • A “Request”: This is a specific question containing instructions of what data is requested

  • A “Request” might include a “Header” parameter, like an access key, so that the API knows that the developer is authorized to access the requested data

  • A database connection: This is the address to where data is stored

  • A “Response”: This is an answer to the “Request” where the requested data has been transformed according to a predefined data structure which the client application can consume, for example “JSON” or “XML”. The structured data is returned to the client application in the response “Body

Example

An API can be compared to a postman delivering letters.

  • The mailbox is the client application where the letter is sent through

  • The request is the envelope with a stamp (“Header”) and address (“Request”) which authorizes the letter to be sent and where it should be sent

  • The response is the actual letter containing sentences (“Response” “Body” with structured data)

Tools for API testing

A common tool for API testing is the “Postman” application. Download the free version from https://www.postman.com/downloads/ and install.

Learn more

Learn more about API basics: https://www.youtube.com/results?search_query=what+is+an+api

2.1 Access the developer portal

Picture

A.   Go to https://developer.byggtjanst.io

B.    Press “SIGN IN

C.    Fill in “Username” and “Password

D.   Press “Sign in

2.2 Access your subscription keys

Picture

A.   Sign in

B.    Press “Keys

C.    Press “Show”, to reveal the “Primary key” for the “CoClass Bas API”. Users should always use the “Primary Key”. The “Secondary key” is used to share it with others temporarily, and it can be revoked as well as re-generated separately

D.   Copy the revealed key. This key value is to be used as the value for “Header” variable “Ocp-Apim-Subscription-Key” when making an API “Request” using the “CoClass Bas API

E.    Press “Show”, to reveal the “Primary key” for the “CoClass Bas API”. Users should always use the “Primary Key”. The “Secondary key” is used to share it with others temporarily, and it can be revoked as well as re-generated separately

F.    Copy the revealed key. This key value is to be used as the value for “Header” variable “Ocp-Apim-Subscription-Key” when making an API ”Request

2.3 Make an API “Request” to “CoClass Bas API” - "Get all root categories"

Picture

“Request”: “Get all root categories”

A.   Press “Products

B.    Press “CoClass Bas

C.   Press “CoClass Public”

D.   Find and press “Get all root categories

E.    Copy “Request URL
The parameters “coClassVersionId” and “language” are both optional. When excluded from the “Request URL” the “Request” will respond with the latest version of CoClass in the Swedish language

F.    Open the “Postman” application

G.   Choose “GET

H.   Paste “Request URL
Please notice the example has excluded the optional parameters “coClassVersionId” and language.

I.      Enter “Header key” “Ocp-Apim-Subscription-Key”. This corresponds to the user subscription key from 2.2 D

J.     Paste “Header key” value for “Ocp-Apim-Subscription-Key

The key value is the revealed value from 2.2 D

K.   Press “Send

L.    Copy “globalIdentifier” for the classification “table” of interest (without “”)

2.4 Make an API “Request” to “CoClass Bas API” - “Get detailed information about a single category with all associated classes”

Picture

“Request”: “Get detailed information about a single category with all associated classes”

A.   Press “Products

B.    Press “CoClass Bas

C.    Press “CoClass Public”

D.   Find and press “Get detailed information about a single category with all associated classes

E.    Copy “Request URL”. The parameter “language” is optional. When excluded from the “Request URL" the “Request” will respond in the Swedish language. The parameter “globalIdentifier” is required. This parameter is value copied from 2.3 L

F.    Open the “Postman” application

G.   Choose “GET

H.   Paste “Request URL
Please notice the example has excluded the optional parameter “language”.

The placeholder “{globalIdentifier}” has been replaced with the parameter is value copied from 2.3 L

I.      Enter “Header key” “Ocp-Apim-Subscription-Key” corresponds to the user subscription key from 2.2 D

J.     Paste “Header key” value for “Ocp-Apim-Subscription-Key”.
The key value is the revealed value from 2.2 D

K.   Press “Send

L.    Find data “Response” of classification “Table” of interest. This data “Response” can either be used in an application, by implementing the API. It can also be saved into a “JSON” file for further manual handling in other applications.

2.5 Make an API "Request" to "CoClass Studio API" - “Get full structure by guid”

Picture

“Request”: “Get full structure by guid” (guid = “Globally Unique Identifier”)

A.   Press “Products

B.    Press “CoClass Bas

C.    Press “CoClass Public Structure”

D.   Find and press “Get full structure by guid

E.    Copy “Request URL
The parameter “language” is optional. When excluded from the “Request URL” the “Request” will respond in the Swedish language

The parameter “structureGuid” is required. This parameter value corresponds to the value copied from 2.5 N

F.    Open the “Postman” application

G.   Go to https://coclass.byggtjanst.se

H.   Press “Logga in

I.      Enter “email” and “password” (not same as user details for https://developer.byggtjanst.se) These shall be the user login details for https://byggtjanst.se

J.     Press “Logga in

K.   Press “My structures

L.    Copy key for api access “structureKey” value. This value will be pasted in 2.5 S

M.  Press the icon of specific structure of interest

N.   Copy “structureGuid” value. This value will be used instead of the placeholder “{structureGuid}” in the “Request URL” in 2.5 P

O.   Choose “GET

P.    Paste key value. Value is copied from 2.5 N

Q.   Enter “Header keys”: “Ocp-Apim-Subscription-Key” and “structureKey”

R.    Paste key value. Value is copied from 2.2 D

S.    Paste key value. Value is copied from 2.5 L

T.    Press “Send

U.   Find data “Response” of specific structure of interest. This data “Response” can either be used in an application, by implementing the API. It can also be saved into a “JSON” file for further manual handling in other applications.

3.1 Frequently asked questions

3.2 Issues or questions?

If you have any issues or questions regarding the CoClass API, contact the CoClass support team by sending an email to coclass@byggtjanst.se.

API Request Parameter Dictionary

Powered by Svensk Byggtjänst.