Dette dokumentet beskriver REN Prosjekt API. APIet er grunnleggende for alt som har med REN-prosjekter å gjøre.

For generell informasjon om tilgang, autentisering og bruk av REN API, se Generelt.

For nettlesergrensesnittet til REN Prosjekt, også kalt REN Prosjektsystem, se https://www.ren.no/project.

Tabell 1. Endringslogg for dokumentet
Dato Beskrivelse

25.01.2019

Første versjon.

Oppbygging

REN Prosjekt API tilbyr funksjonalitet for opprettelse og sletting av prosjekter, søk blant prosjekter, arkivering m.m.

Den egentlige merverdien i et REN-prosjekt ligger i verktøyene som kan knyttes til prosjektet. Internt kalles disse moduler, og de eksponerer sine egne APIer. REN Prosjekt API inkluderer aktivering, listing og fjerning av moduler, men stopper der. Videre kommunikasjon med moduler gjøres via deres egne APIer. API-kommunikasjon innenfor et REN-prosjekt vil dermed sannsynligvis bruke endepunkter i en rekke forskjellige APIer. Dette er en strukturell ansvarsfordeling og har lite å si for selve bruken av REN webtjenester.

Prosjekt-ID

Prosjekt-ID er den primære identifikatoren for et prosjekt, og skal som regel brukes når man peker ut et prosjekt i APIet. Prosjekt-ID er en intern ID som ikke har betydning utenfor systemet. Derfor bør prosjekt-ID i eksterne system lagres ved opprettelse av REN-prosjekt. Alternativt kan den integrerende parten søke opp prosjekt basert på prosjektnummer, saksnummer og lignende - men vil da være nødt til å håndtere å få treff på flere enn ett prosjekt.

Prosjektnummer er foreløpig, av historiske grunner, unikt per selskap. Når det gamle SOAP-APIet er faset ut vil det være mulig å fjerne denne begrensningen.

  • Det nye REST-APIet forventer således ikke at prosjektnummer er unikt, og integrerende parter må også forholde seg til den muligheten.

  • Samtidig, så lenge begrensningen er der må unike prosjektnummer oppgis. Alternativt må eksisterende prosjekt med samme prosjektnummer slettes før prosjektnummeret kan gjenbrukes.

URL base path

Base path for REN Prosjekt API er https://api.ren.no/public/project/rest.

Prosjekter

Opprettelse og sletting

Når et prosjekt skal opprettes må en ansvarlig (personlig eier) oppgis. Bodyen skal være en JSON-struktur i samme Project-format som man får når man henter et prosjekt.

Moduler kan aktiveres umiddelbart gjennom query-parameter 'moduleType'.

f.eks.

{
   "companyId": 12345,
   "location": {
       "address": {
           "address1": "CONRAD MOHRS VEG",
           "city": "Bergen",
           "zipCode": "5068"
       },
   },
   "name": "Eksempelprosjekt",
   "number": "EKSEMPEL-12345",
   "startDate": "2019-01-01",
   "status": "NEW"
}

Sletting utføres med følgende:

Søke opp prosjekter

Det finnes flere muligheter for å hente, liste og søke opp prosjekter. For å hente informasjon om et enkelt prosjekt med kjent prosjekt-ID benyttes følgende:

For å liste opp alle prosjekter som din bruker har tilgang til kan følgende benyttes:

For å hente alle prosjekter (som din bruker har tilgang til) i et selskap:

Selskaps-IDer er felles i alle REN-system. Du finner IDen for ditt eget selskap fra din egen profil, fra et eksisterende prosjekt eid av selskapet, eller på forespørsel til REN.

Det er også mulig å finne prosjekter basert på prosjektnummer, nettstasjonsnummer (engelsk: substation reference) eller saksnummer (engelsk: case reference):

For andre søkekriterier samt mer avansert filtrering og paginering kan følgende endepunkt benyttes:

Dette endepunktet muliggjør filtrering på status, prosjektansvarlig, aktiverte modultyper, startdato m.m. Se API dokumentasjonen for detaljer. Dette er også det eneste endepunktet som lar deg søke i prosjektarkivet. For å unngå at prosjekter fra prosjektarkivet blir inkludert med dette endepunktet må 'archived=false' oppgis som query-parameter!

Arkivering

REN prosjekter støtter en forenklet arkiveringsfunksjon. I praksis betyr arkivering at et prosjekt ikke dukker opp i vanlige prosjektlister. For å se arkiverte prosjekter må det komplette søks-og-paginerings-endepunktet benyttes (se forrige paragraf). For å flytte et prosjekt til eller fra arkivet benyttes følgende endepunkter:

Oppdatering

En del (men ikke all) prosjekt-meta-data kan oppdateres. For å dedikert oppdatere status eller ansvarlig kan følgende endepunkter benyttes:

For oppdatering av andre egenskaper kan et generelt oppdaterings-endepunkt brukes:

Her skal bodyen være en JSON prosjektstruktur i samme format som man får når man henter et prosjekt. Se Project for detaljer. For å unngå at egenskaper blir overskrevet uten vilje, er det anbefalt å oppgi hvilke egenskaper som skal oppdateres med query-parameter property. Her er et eksempel på dette:

{
   "status": "STARTED",
   "endDate": "2019-31-07",
   "endDateEstimate": "2019-31-07"
}

Moduler

Det er mulig å spørre APIet hvilke moduler som er tilgjengelige med brukerens tilganger, i den gjeldende versjonen av REN Prosjekt. REST-endepunkten for dette er:

For å finne ut hvilke moduler som er aktivert i et prosjekt kan følgende REST-endepunkt benyttes:

I et prosjekt vil det aldri finnes flere moduler av samme modultype. Det er tillatt å prøve å aktivere en allerede aktivert modultype, men dette vil ikke ha noen effekt. For aktivering og fjerning av modultyper kan følgende REST-endepunkter benyttes:

API-dokumentasjon

Dokumentasjonen over endepunktene og datastrukturene er generert og skrevet på engelsk. Du kan lese den samt prøve ut endepunktene i REN sin API Browser. Den dokumentasjonen er live-generert og gjenspeiler den versjon som faktisk kjører. Alternativt kan du fortsette å lese en statisk generert versjon her.

Gå til API Browser

Resources

Module

List project modules
GET /modules/by-projectid/{projectId}
Description

Lists all modules that have been added to a project.

Parameters
Type Name Schema

Path

projectId
required

integer (int64)

Responses
HTTP Code Description Schema

200

successful operation

< Module > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

Add a module to a project
POST /modules/by-projectid/{projectId}/by-moduletype/{moduleType}
Description

Add a module to a project. Won’t do anything in case this module type has already been added.

Parameters
Type Name Description Schema

Path

moduleType
required

The module type. See ModuleType for details.

enum (CALCULATION, ROADLIGHT, LVPOLE, COCO)

Path

projectId
required

integer (int64)

Responses
HTTP Code Description Schema

200

successful operation

Module

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

Get a project module
GET /modules/by-projectid/{projectId}/by-moduletype/{moduleType}
Parameters
Type Name Description Schema

Path

moduleType
required

The module type. See ModuleType for details.

enum (CALCULATION, ROADLIGHT, LVPOLE, COCO)

Path

projectId
required

integer (int64)

Responses
HTTP Code Description Schema

200

successful operation

Module

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

Remove a module from a project
DELETE /modules/by-projectid/{projectId}/by-moduletype/{moduleType}
Parameters
Type Name Description Schema

Path

moduleType
required

The module type. See ModuleType for details.

enum (CALCULATION, ROADLIGHT, LVPOLE, COCO)

Path

projectId
required

integer (int64)

Responses
HTTP Code Description Schema

default

successful operation

No Content

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

List available module types
GET /modules/types
Description

List all available module types. Will only report back modules that you have access to.

Responses
HTTP Code Description Schema

200

successful operation

< ModuleType > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

oauth2

oauth2-client

prosjektsystem.bruker

Project

List all projects
GET /projects
Description

List all projects that you have access to.

Responses
HTTP Code Description Schema

200

successful operation

< Project > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

List all projects for a company
GET /projects/by-companyid/{companyId}
Description

List all projects for a company. Will only return projects that you have access to.

Parameters
Type Name Schema

Path

companyId
required

integer (int64)

Responses
HTTP Code Description Schema

200

successful operation

< Project > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

List projects by company and case reference
GET /projects/by-companyid/{companyId}/by-caseref/{caseRef}
Description

List all projects for a company and specified case reference (norsk: saksnummer). Will only return projects that you have access to.

Parameters
Type Name Description Schema

Path

caseRef
required

The case reference.

string

Path

companyId
required

integer (int64)

Responses
HTTP Code Description Schema

200

successful operation

< Project > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

List projects by company and number
GET /projects/by-companyid/{companyId}/by-number/{number}
Description

List all projects for a company and specified project number. Will only return projects that you have access to.

Parameters
Type Name Schema

Path

companyId
required

integer (int64)

Path

number
required

string

Responses
HTTP Code Description Schema

200

successful operation

< Project > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

List projects by company and substation reference
GET /projects/by-companyid/{companyId}/by-substationref/{substationRef}
Description

List all projects for a company and specified substation reference (norsk: nettstasjonsnummer). Will only return projects that you have access to.

Parameters
Type Name Description Schema

Path

companyId
required

integer (int64)

Path

substationRef
required

The substation reference.

string

Responses
HTTP Code Description Schema

200

successful operation

< Project > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

Create a project
PUT /projects/by-owner/{owner}
Description

Create a new project. The following properties are required for the Project body: number, name, status and startDate. Providing values for more properties (e.g. endDateEstimate, substationRef, caseRef, location, …) is highly recommended. Modules can be activated immediately via query parameter moduleType. Additional modules can be added later via Add a module to a project. The value of property id in the Project response should be saved for further interaction with the added project.

Parameters
Type Name Description Schema

Path

owner
required

The username or email of the project owner (e.g. your own username or email). Required since each project must have an owner / responsible.

string

Query

moduleType
optional

Optional module types that should automatically be activated for the newly created project. See ModuleType for details.

< enum (CALCULATION, ROADLIGHT, LVPOLE, COCO) > array(multi)

Body

body
required

Project

Responses
HTTP Code Description Schema

200

successful operation

Project

Consumes
  • application/json;charset=utf-8

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

Search for projects
GET /projects/page
Description

Search for projects, or get all (or filtered) projects. This endpoint supports pagination, and will only return projects that you have access to. Unlike most other endpoints, this endpoint can also list archived projects (depending on parameter archived).

Parameters
Type Name Description Schema Default

Query

accessScope
optional

Filter by your own access scope. See AccessScope.

< enum (IMPLICIT, EXPLICIT) > array(multi)

Query

accessed
optional

Limit to projects that have / have not been accessed by you.

boolean

Query

archived
optional

Filter by archived state. Specify false here to behave like the other endpoints. Leaving this filter blank will - unlike most endpoints - include both archived and unarchived projects.

boolean

Query

caseRef
optional

Filter by case references (norsk: saksnummer).

< string > array(multi)

Query

companyId
optional

Filter by company ID.

< integer (int64) > array(multi)

Query

count
optional

The page size / maximum number of projects to return.

integer (int32)

10

Query

first
optional

Optional offset when using pagination.

integer (int32)

0

Query

fromStartDate
optional

The oldest accepted start date. May be specified alone or together with toStartDate.

string (date-time)

Query

hasLocation
optional

Limit to projects that have / do not have a geographical location defined.

boolean

Query

moduleType
optional

Filter by activated module types. See ModuleType.

< enum (CALCULATION, ROADLIGHT, LVPOLE, COCO) > array(multi)

Query

myPermissionTypes
optional

Filter by your own permission types. See PermissionType.

< enum (READ, WRITE) > array(multi)

Query

myProjectRoles
optional

Filter by your own project roles. See ProjectRole.

< enum (READER, WRITER, OWNER) > array(multi)

Query

number
optional

Filter by project numbers.

< string > array(multi)

Query

owner
optional

Filter by (personal) owner / responsible username or email.

< string > array(multi)

Query

q
optional

Optional query string, composed of one or multiple search words.

string

Query

sort
optional

Optional sorting instructions. The syntax is [-]<property>, where <property> is the name of a project property, and the optional minus implies descending order. See Project for available properties.

< string > array(multi)

Query

status
optional

Filter by status. See ProjectStatus.

< enum (NEW, STARTED, ENDED) > array(multi)

Query

substationRef
optional

Filter by substation references (norsk: nettstasjonsnummer).

< string > array(multi)

Query

toStartDate
optional

The newest accepted start date. May be specified alone or together with fromStartDate.

string (date-time)

Responses
HTTP Code Description Schema

200

successful operation

PaginatedProject

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

Get property summaries
GET /projects/summary
Description

Get property summaries for all (or filtered) projects. This endpoint provides aggregated information that is useful when searching for projects. Unlike most other endpoints, this endpoint can also include archived projects (depending on parameter archived).

Parameters
Type Name Description Schema

Query

accessScope
optional

Filter by your own access scope. See AccessScope.

< enum (IMPLICIT, EXPLICIT) > array(multi)

Query

accessed
optional

Limit to projects that have / have not been accessed by you.

boolean

Query

archived
optional

Filter by archived state. Specify false here to behave like the other endpoints. Leaving this filter blank will - unlike most endpoints - include both archived and unarchived projects.

boolean

Query

caseRef
optional

Filter by case references (norsk: saksnummer).

< string > array(multi)

Query

companyId
optional

Filter by company ID.

< integer (int64) > array(multi)

Query

fromStartDate
optional

The oldest accepted start date. May be specified alone or together with toStartDate.

string (date-time)

Query

hasLocation
optional

Limit to projects that have / do not have a geographical location defined.

boolean

Query

moduleType
optional

Filter by activated module types. See ModuleType.

< enum (CALCULATION, ROADLIGHT, LVPOLE, COCO) > array(multi)

Query

myPermissionTypes
optional

Filter by your own permission types. See PermissionType.

< enum (READ, WRITE) > array(multi)

Query

myProjectRoles
optional

Filter by your own project roles. See ProjectRole.

< enum (READER, WRITER, OWNER) > array(multi)

Query

number
optional

Filter by project numbers.

< string > array(multi)

Query

owner
optional

Filter by (personal) owner / responsible username or email.

< string > array(multi)

Query

q
optional

Optional query string, composed of one or multiple search words.

string

Query

status
optional

Filter by status. See ProjectStatus.

< enum (NEW, STARTED, ENDED) > array(multi)

Query

substationRef
optional

Filter by substation references (norsk: nettstasjonsnummer).

< string > array(multi)

Query

toStartDate
optional

The newest accepted start date. May be specified alone or together with fromStartDate.

string (date-time)

Responses
HTTP Code Description Schema

200

successful operation

MultiPropertySummary

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

Get a project by ID
GET /projects/{projectId}
Parameters
Type Name Schema

Path

projectId
required

integer (int64)

Responses
HTTP Code Description Schema

200

successful operation

Project

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

Update a project
PUT /projects/{projectId}
Description

Update project meta-data. Most, but not all properties can be updated.

Parameters
Type Name Description Schema

Path

projectId
required

integer (int64)

Query

property
optional

A list of named properties that should be updated. Other properties will remain untouched. See Project for available properties, but keep in mind that all of them cannot be updated this way.

< string > array(multi)

Body

body
required

Project

Responses
HTTP Code Description Schema

200

successful operation

Project

Consumes
  • application/json;charset=utf-8

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

Delete a project
DELETE /projects/{projectId}
Parameters
Type Name Schema

Path

projectId
required

integer (int64)

Responses
HTTP Code Description Schema

default

successful operation

No Content

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

Move a project to the archive
PUT /projects/{projectId}/archive
Description

Move a project to the archive. An archived project will not show up in normal project lists.

Parameters
Type Name Schema

Path

projectId
required

integer (int64)

Responses
HTTP Code Description Schema

default

successful operation

No Content

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

Restore a project from the archive
DELETE /projects/{projectId}/archive
Parameters
Type Name Schema

Path

projectId
required

integer (int64)

Responses
HTTP Code Description Schema

default

successful operation

No Content

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

Change project owner
PUT /projects/{projectId}/owner/{owner}
Parameters
Type Name Description Schema

Path

owner
required

The username or email of the new project owner / responsible.

string

Path

projectId
required

integer (int64)

Responses
HTTP Code Description Schema

default

successful operation

No Content

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

Change project status
PUT /projects/{projectId}/status/{projectStatus}
Parameters
Type Name Description Schema

Path

projectId
required

integer (int64)

Path

projectStatus
required

The new project status. ProjectStatus for details.

enum (NEW, STARTED, ENDED)

Responses
HTTP Code Description Schema

default

successful operation

No Content

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

Definitions

AccessScope

Models the scope of a granted access. Valid values are:

  • IMPLICIT Implicit access, e.g. via company or department.

  • EXPLICIT Explicit access, e.g. via ownership.

Type : enum (IMPLICIT, EXPLICIT)

Address

Models a physical address.

Name Schema

address1
optional

string

address2
optional

string

city
optional

string

countryCode
optional

string

zipCode
optional

string

Comparable

Type : object

Coordinate

Models a coordinate.

Name Schema

latitude
optional

number (double)

longitude
optional

number (double)

CoordinateSource

Specifies the source of a coordinate. Valid values are:

  • ROUGH_ADDRESS The coordinate is based on a rough, inexact address.

  • EXACT_ADDRESS The coordinate is based on an exact address.

  • MANUAL The coordinate has been manually modified.

Type : enum (ROUGH_ADDRESS, EXACT_ADDRESS, MANUAL)

Location

Models a location, possibly with both address and coordinate.

Name Schema

address
optional

Address

coordinate
optional

Coordinate

coordinateSource
optional

CoordinateSource

Module

Basic information about a project module.

Name Description Schema

projectId
optional

A numeric identifier identifying the project.

integer (int64)

type
optional

Type of module.

ModuleType

ModuleType

Represents the types of modules / tools the a project can contain. Valid values are:

  • CALCULATION (norsk: Kalkyle)

  • ROADLIGHT (norsk: Veilys)

  • LVPOLE (norsk: LS-mast)

  • COCO (norsk: Anleggsbidrag)

Type : enum (CALCULATION, ROADLIGHT, LVPOLE, COCO)

MultiPropertySummary

Name Schema

counter
optional

QuantityCounter

propertySummaries
optional

< string, PropertySummary > map

staticCounter
optional

QuantityCounter

Paginated

Name Schema

count
optional

integer (int32)

entities
optional

< object > array

first
optional

integer (int32)

total
optional

integer (int32)

PaginatedProject

Name Schema

count
optional

integer (int32)

entities
optional

< Project > array

first
optional

integer (int32)

total
optional

integer (int32)

PermissionType

Models permission types.

Type : enum (READ, WRITE)

Project

General information about a project.

Name Description Schema

archived
optional

Indicates if the project is archived.

boolean

caseRef
optional

A case reference (norsk: saksnummer) for the project.

string

companyId
optional

A numeric identifier for the company of this project.

integer (int64)

createdBy
optional

The user that created the project.

string

createdDate
optional

The timestamp for when the project was created.

string (date-time)

description
optional

A description for the project.

string

endDate
optional

The end date for the project.

string (date-time)

endDateEstimate
optional

The estimated end date for the project.

string (date-time)

id
optional

A unique numeric identifier.

integer (int64)

location
optional

The location (address and/or coordinate) for the project.

Location

meta
optional

Meta information originating from project modules.

ProjectMeta

modifiedBy
optional

The user that modified the project.

string

modifiedDate
optional

The timestamp for when the project was modified.

string (date-time)

name
optional

A name describing the project.

string

number
optional

A number/id identifying the project. Is required to be unique within a company.

string

readonly
optional

Indicates if the project is read only.

boolean

startDate
optional

The start date for the project.

string (date-time)

status
optional

The status for the project.

ProjectStatus

substationRef
optional

A substation reference (norsk: nettstasjonsnummer) for the project.

string

ProjectMeta

Read-only project meta data, originating from project modules.

Name Description Schema

catalogRevisionName
optional

The name of the revision (norsk: kostnadskatalog revisjon) used in the calculation module.

string

totalCost
optional

The total cost from the calculation module (norsk: kalkylesum).

number (double)

ProjectRole

Models the role of a user within a project. Valid values are:

  • READER (norsk: Har lesetilgang til prosjektet)

  • WRITER (norsk: Har skrivetilgang til prosjektet)

  • OWNER (norsk: Eier av prosjektet)

Type : enum (READER, WRITER, OWNER)

ProjectStatus

Models the high level status of a project. Valid values are:

  • NEW (norsk: Ikke påbegynt)

  • STARTED (norsk: Påbegynt)

  • ENDED (norsk: Avsluttet)

Type : enum (NEW, STARTED, ENDED)

PropertySummary

Name Schema

displayName
optional

string

name
optional

string

op
optional

enum (OR, AND)

range
optional

RangeObject

valueSummaries
optional

< PropertyValueSummary > array

PropertyValueSummary

Name Schema

counter
optional

QuantityCounter

displayValue
optional

string

value
optional

object

QuantityCounter

Name Schema

count
optional

integer (int64)

quantity
optional

integer (int64)

Range

Name Schema

displayName
optional

string

from
optional

Comparable

to
optional

Comparable

RangeObject

Name Schema

displayName
optional

string

from
optional

object

to
optional

object

Security

oauth2-password

A flow where an end user is required. Endpoints using this flow can provide personal customization and access to personal information.

Name Description

prosjektsystem.bruker

Implies that role 'prosjektsystem.bruker' is required.

oauth2-client

A flow where an end user is not involved. Endpoints using this flow will support full automation without any human intervention, but on the other hand cannot provide personal customization or access to personal information.

Name Description

prosjektsystem.bruker

Implies that role 'prosjektsystem.bruker' is required.