Dette dokumentet beskriver REN Dokument API. APIet muliggjør søk og nedlasting av RENblad og andre REN-dokumenter.

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

For det offisielle nettlesergrensesnittet for å søke blant RENblad, se http://www.ren.no/ren-blad.

Tabell 1. Endringslogg for dokumentet
Dato Beskrivelse

19.02.2018

Første versjon.

27.06.2018

Mer tekst og eksempler til kapittel "Oppbyggning".

25.01.2019

Endringer i kapittelinndeling samt noen tekstuelle endringer.

Oppbygging

REN Dokument API gir tilgang til meta-data for et utvalg av REN-dokumenter - hovedsaklig RENblad og REN-nytt. Gjennom denne informasjonen kan man finne versjons-historikk, selskapsmerknader (krever brukerautentisering), favorittlister (krever brukerautentisering) m.m. APIet tilbyr også en mulighet for et ganske fleksibelt søk blant dokumentene. Nedlasting av dokumenter er selvfølgelig også støttet.

Identifisering av dokumenter

Meta-dataene og ressursene i dette APIet bruker ofte dokument-identifikatorer. Disse kan forekomme i to varianter:

  • en uversjonert identifikator {type}-{nummer}

  • en versjonert identifikator {type}-{nummer}:{versjon}

Her står {type} for dokumenttypen, f.eks. renblad. Den påfølgende {nummer} er en tekststreng som er unik innenfor dokumenttypen. Den er ikke nødvendigvis kun numerisk. Den opsjonelle delen {versjon} kan brukes for å peke ut en annen versjon enn "den siste" eller "alle versjoner".

Endepunkter i dette APIet bruker som regel tilsvarende identifisering, men gjør det gjennom en hierarkisk URL:

  • …​/{type} gjelder alle dokumenter av den typen.

  • …​/{type}/{nummer} gjelder enten for alle versjoner eller for den siste versjonen av et dokument.

  • …​/{type}/{nummer}/{versjon} gjelder kun for en eksakt versjon av et dokument.

URL base path

Base path for REN Dokument API er https://api.ren.no/public/doc/rest.

Eksempler

Laste ned RENblad 5000:

Hente meta-data for alle RENblad:

Hente meta-data for den siste versjonen av RENblad 5000:

Hente meta-data for alle versjoner av RENblad 5000:

Hente meta-data for den første versjonen av RENblad 5000:

Hente meta-data for flere RENblad:

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

Download

Download the latest version of a document
GET /download/{type}/{number}
Description

If user based authentication is used, then an additional front page can be rendered for documents that have company comments. Parameters user and sourcecompany will be ignored in case userless authentication is used.

Parameters
Type Name Description Schema

Path

number
required

The document number.

string

Path

type
required

The type of the document to download.

enum (RENBLAD, RENNYTT)

Query

sourcecompanyid
optional

An optional list of source company IDs. If specified, company comments will only be returned for for the specified companies.

< integer (int64) > array(multi)

Query

user
optional

The username or email of the authenticated user (if accessed in the context of a user).

string

Responses
HTTP Code Description Schema

default

successful operation

No Content

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

oauth2

oauth2-client

rensystemer

Download a specific version of a document
GET /download/{type}/{number}/{version}
Description

If user based authentication is used, then an additional front page can be rendered for documents that have company comments. Parameters user and sourceCompany will be ignored in case userless authentication is used.

Parameters
Type Name Description Schema

Path

number
required

The document number.

string

Path

type
required

The type of the document to download.

enum (RENBLAD, RENNYTT)

Path

version
required

The version of the document, e.g. '1.0'.

string

Query

sourcecompanyid
optional

An optional list of source company IDs. If specified, company comments will only be returned for for the specified companies.

< integer (int64) > array(multi)

Query

user
optional

The username or email of the authenticated user (if accessed in the context of a user).

string

Responses
HTTP Code Description Schema

default

successful operation

No Content

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

oauth2

oauth2-client

rensystemer

Meta-data

Find documents based on custom identification criteria
GET /meta
Description

Can be used to lookup multiple document types and / or multiple document instances in a single request. Similar to a search, but only works on identity and not on content. Will return the latest version of each document in case history is 'false' or missing. Will return all versions in case history is 'true'.

Parameters
Type Name Description Schema Default

Query

access
optional

Optionally restrict lookup to documents for which you have / do not have access.

enum (ANY, ALLOWED, DENIED)

Query

history
optional

Should be 'true' to also look up older versions, otherwise 'false'.

boolean

"false"

Query

number
optional

Restrict to these document numbers within all document types.

< string > array(multi)

Query

obsolete
optional

Should be 'true' to also look up obsolete documents, otherwise 'false'.

boolean

"false"

Query

sourcecompanyid
optional

An optional list of source company IDs. If specified, company comments will only be returned for for the specified companies.

< integer (int64) > array(multi)

Query

type
optional

Restrict to these document types. All document types will be searched in case this parameter is left out.

< enum (RENBLAD, RENNYTT) > array(multi)

Query

user
optional

The username or email of the authenticated user (if accessed in the context of a user). Optional, but needed for certain personalized meta-data.

string

Responses
HTTP Code Description Schema

200

successful operation

< DocData > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

oauth2

oauth2-client

rensystemer

Check access level
GET /meta/access/{type}/{number}
Description

Check if the you have access to a document.

Parameters
Type Name Description Schema

Path

number
required

The document number.

string

Path

type
required

The type of the document to look for.

enum (RENBLAD, RENNYTT)

Query

user
optional

The username or email of the user (if accessed in the context of a user).

string

Responses
HTTP Code Description Schema

200

successful operation

boolean

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

oauth2

oauth2-client

rensystemer

GET /meta/backlink/{type}/{number}
Description

Retrieve all documents that references a specified document . i.e. the opposite of the links in the document itself.

Parameters
Type Name Description Schema

Path

number
required

The document number.

string

Path

type
required

The type of document to check.

enum (RENBLAD, RENNYTT)

Query

sourcecompanyid
optional

An optional list of source company IDs. If specified, company comments will only be returned for for the specified companies.

< integer (int64) > array(multi)

Query

user
optional

The username or email of the authenticated user (if accessed in the context of a user). Optional, but needed for certain personalized meta-data.

string

Responses
HTTP Code Description Schema

200

successful operation

< DocData > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

oauth2

oauth2-client

rensystemer

Get companies sharing comments from
GET /meta/comment/sharing/from
Description

Find out which companies share their comments with a given company. User-based authentication must be used for this endpoint.

Parameters
Type Name Description Schema Default

Query

company
optional

The company ID. May be left out, in which case it is looked up from the specified user.

integer (int64)

Query

own
optional

If 'true', then the specified company itself will be included in the list.

boolean

"true"

Query

user
optional

The username or email of the authenticated user. The company ID can be derived from it.

string

Responses
HTTP Code Description Schema

200

successful operation

< Company > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

Get companies sharing comments to
GET /meta/comment/sharing/to
Description

Find out to which companies a specified company shares its comments. User-based authentication must be used for this endpoint.

Parameters
Type Name Description Schema Default

Query

company
optional

The company ID. May be left out, in which case it is looked up from the specified user.

integer (int64)

Query

own
optional

If 'true', then the specified company itself will be included in the list.

boolean

"true"

Query

user
optional

The username or email of the authenticated user. The company ID can be derived from it.

string

Responses
HTTP Code Description Schema

200

successful operation

< Company > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

Get company comments for a document type
GET /meta/comment/{type}
Description

Retrieve all company comments for a specified document type and company. User-based authentication must be used for this endpoint.

Parameters
Type Name Description Schema

Path

type
required

The type of the documents.

enum (RENBLAD, RENNYTT)

Query

company
optional

The company ID. May be left out, in which case it is looked up from the specified user.

integer (int64)

Query

sourcecompanyid
optional

An optional list of source company IDs. If specified, company comments will only be returned for for the specified companies.

< integer (int64) > array(multi)

Query

user
optional

The username or email of the authenticated user. The company ID can be derived from it.

string

Responses
HTTP Code Description Schema

200

successful operation

< Comment > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

Get company comments for a document
GET /meta/comment/{type}/{number}
Description

Retrieve the company comments for a specified document and company. User-based authentication must be used for this endpoint.

Parameters
Type Name Description Schema

Path

number
required

The document number.

string

Path

type
required

The type of the document.

enum (RENBLAD, RENNYTT)

Query

company
optional

The company ID. May be left out, in which case it is looked up from the specified user.

integer (int64)

Query

sourcecompanyid
optional

An optional list of source company IDs. If specified, company comments will only be returned for for the specified companies.

< integer (int64) > array(multi)

Query

user
optional

The username or email of the authenticated user. The company ID can be derived from it.

string

Responses
HTTP Code Description Schema

200

successful operation

< Comment > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

Get favorite documents
GET /meta/favorite/{type}
Description

List meta-data for the documents marked as personal favorites by the authenticated/specified user. User-based authentication must be used for this endpoint.

Parameters
Type Name Description Schema

Path

type
required

The type of document to check.

enum (RENBLAD, RENNYTT)

Query

user
optional

The username or email of the user whose favorite list to return.

string

Responses
HTTP Code Description Schema

200

successful operation

< DocData > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

Get favorite document IDs
GET /meta/favorite/{type}/ids
Description

List the IDs of documents marked as personal favorites by the authenticated/specified user. User-based authentication must be used for this endpoint.

Parameters
Type Name Description Schema

Path

type
required

The type of document to check.

enum (RENBLAD, RENNYTT)

Query

user
optional

The username or email of the user whose favorite list to return.

string

Responses
HTTP Code Description Schema

200

successful operation

< string > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

Get popular documents
GET /meta/popular/{type}
Description

Retrieve an ordered list of meta-data for the most popular (among all users) documents.

Parameters
Type Name Description Schema Default

Path

type
required

The type of document to check.

enum (RENBLAD, RENNYTT)

Query

days
optional

The number of days to base the statistics on, from now, back in time.

integer (int32)

60

Responses
HTTP Code Description Schema

200

successful operation

< DocData > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

oauth2

oauth2-client

rensystemer

Get popular document IDs
GET /meta/popular/{type}/ids
Description

Retrieve an ordered list of IDs for the most popular (among all users) documents.

Parameters
Type Name Description Schema Default

Path

type
required

The type of document to check.

enum (RENBLAD, RENNYTT)

Query

days
optional

The number of days to base the statistics on, from now, back in time.

integer (int32)

60

Responses
HTTP Code Description Schema

200

successful operation

< string > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

oauth2

oauth2-client

rensystemer

Get recent documents
GET /meta/recent/{type}
Description

Retrieve an ordered list of meta-data for the most recently accessed documents (by the authenticated user). User-based authentication must be used for this endpoint.

Parameters
Type Name Description Schema

Path

type
required

The type of document to check.

enum (RENBLAD, RENNYTT)

Query

user
optional

The username or email of the user whose recent list should be returned.

string

Responses
HTTP Code Description Schema

200

successful operation

< DocData > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

Get recent document IDs
GET /meta/recent/{type}/ids
Description

Retrieve an ordered list of IDs for the most recently accessed documents (by the authenticated user). User-based authentication must be used for this endpoint.

Parameters
Type Name Description Schema

Path

type
required

The type of document to check.

enum (RENBLAD, RENNYTT)

Query

user
optional

The username or email of the user whose recent list should be returned.

string

Responses
HTTP Code Description Schema

200

successful operation

< string > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

Get RENblad series
GET /meta/renblad-series
Description

Returns information about all RENblad series.

Responses
HTTP Code Description Schema

200

successful operation

< RenbladSeries > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

oauth2

oauth2-client

rensystemer

GET /meta/search
Description

This endpoint provides more advanced searching than the other endpoints that find documents. Textual search within document contents is supported, and additional filtering is supported via facet constraints. The result will be sorted and paginated.

Parameters
Type Name Description Schema Default

Query

access
optional

Optionally restrict lookup to documents for which you have / do not have access.

enum (ANY, ALLOWED, DENIED)

Query

fc
optional

Optional facet constraints.

< string > array(multi)

Query

history
optional

Should be 'true' to also look up older versions, otherwise 'false'.

boolean

"false"

Query

max
optional

The maximum number of matches to return, i.e. the page size.

integer (int32)

1000

Query

obsolete
optional

Should be 'true' to also look up obsolete documents, otherwise 'false'.

boolean

"false"

Query

q
optional

Free format text to search for, within the document contents.

string

Query

scope
optional

Optionally limit the search to a predefined sub-scope.

enum (ALL, FAVORITES, USED, POPULAR, COMMENTED, MAIN)

"ALL"

Query

sort
optional

Optional sorting instructions. The syntax is `[-]<property>`, where <property> is one of the values supported by DocProperty, and the optional minus implies descending order.

< string > array(multi)

Query

sourcecompanyid
optional

An optional list of source company IDs. If specified, company comments will only be returned for for the specified companies. For scope COMMENTED, only documents commented by the specified companies will be returned.

< integer (int64) > array(multi)

Query

start
optional

The first match to return, i.e. the page offset.

integer (int32)

0

Query

type
optional

Restricts the search to these document types. All document types will be searched in case this parameter is left out.

< enum (RENBLAD, RENNYTT) > array(multi)

Query

user
optional

The username or email of the authenticated user (if accessed in the context of a user). Optional, but needed for certain personalized meta-data.

string

Responses
HTTP Code Description Schema

200

successful operation

SearchData

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

oauth2

oauth2-client

rensystemer

Auto-suggest search text
GET /meta/suggestion
Description

Ask for auto-complete word suggestions for typed in search text. Typically used in combination with the GET /search endpoint.

Parameters
Type Name Description Schema

Query

fc
optional

Optional facet constraints.

< string > array(multi)

Query

q
optional

The free format search text that is to be auto-completed.

string

Query

types
optional

The document types that are to be searched. All document types will be scanned in case this parameter is left out.

< enum (RENBLAD, RENNYTT) > array(multi)

Query

user
optional

The username or email of the authenticated user (if accessed in the context of a user). Optional, but needed for certain personalized meta-data.

string

Responses
HTTP Code Description Schema

200

successful operation

SuggestData

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

oauth2

oauth2-client

rensystemer

Get document versions
GET /meta/version/{type}/{number}
Description

Get information about all versions of a specified document. The returned list is ordered by descending version.

Parameters
Type Name Description Schema

Path

number
required

The document number.

string

Path

type
required

The type of the document to fetch versions for.

enum (RENBLAD, RENNYTT)

Query

user
optional

The username or email of the authenticated user (if accessed in the context of a user). Optional, but needed for certain personalized meta-data.

string

Responses
HTTP Code Description Schema

200

successful operation

< Version > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

oauth2

oauth2-client

rensystemer

Find all documents of a specified type
GET /meta/{type}
Description

Will return the latest version of each document in case history is 'false' or missing. Will return all versions in case history is 'true'.

Parameters
Type Name Description Schema Default

Path

type
required

The type of documents to look for.

enum (RENBLAD, RENNYTT)

Query

access
optional

Optionally restrict lookup to documents for which you have / do not have access.

enum (ANY, ALLOWED, DENIED)

Query

history
optional

Should be 'true' to also look up older versions, otherwise 'false'.

boolean

"false"

Query

obsolete
optional

Should be 'true' to also look up obsolete documents, otherwise 'false'.

boolean

"false"

Query

sourcecompanyid
optional

An optional list of source company IDs. If specified, company comments will only be returned for for the specified companies.

< integer (int64) > array(multi)

Query

user
optional

The username or email of the authenticated user (if accessed in the context of a user). Optional, but needed for certain personalized meta-data.

string

Responses
HTTP Code Description Schema

200

successful operation

< DocData > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

oauth2

oauth2-client

rensystemer

Get a document
GET /meta/{type}/{number}
Description

Will return the latest version of the document in case history is 'false' or missing. Will return all versions in case history is 'true'.

Parameters
Type Name Description Schema Default

Path

number
required

The document number.

string

Path

type
required

The type of the document to look for.

enum (RENBLAD, RENNYTT)

Query

history
optional

Should be 'true' to also look up older versions, otherwise 'false'.

boolean

"false"

Query

sourcecompanyid
optional

An optional list of source company IDs. If specified, company comments will only be returned for for the specified companies.

< integer (int64) > array(multi)

Query

user
optional

The username or email of the authenticated user (if accessed in the context of a user). Optional, but needed for certain personalized meta-data.

string

Responses
HTTP Code Description Schema

200

successful operation

< DocData > array

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

oauth2

oauth2-client

rensystemer

Get a specific version of a document
GET /meta/{type}/{number}/{version}
Parameters
Type Name Description Schema

Path

number
required

The document number.

string

Path

type
required

The type of the document to look for.

enum (RENBLAD, RENNYTT)

Path

version
required

The version of the document, e.g. '1.0'.

string

Query

sourcecompanyid
optional

An optional list of source company IDs. If specified, company comments will only be returned for for the specified companies.

< integer (int64) > array(multi)

Query

user
optional

The username or email of the authenticated user (if accessed in the context of a user). Optional, but needed for certain personalized meta-data.

string

Responses
HTTP Code Description Schema

200

successful operation

DocData

Produces
  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

rensystemer

oauth2

oauth2-client

rensystemer

Definitions

Collation

Name Schema

text
optional

string

Comment

Name Schema

company
optional

Company

displayModifiedBy
optional

string

docId
optional

string

modifiedBy
optional

string

modifiedDate
optional

string (date-time)

sharedToCompanyId
optional

integer (int64)

text
optional

string

Company

Name Schema

id
optional

integer (int64)

name
optional

string

DocData

Meta-data for a document.

Name Schema

activity1
optional

< string > array

activity2
optional

< string > array

capabilities
optional

< enum (HISTORY, HISTORY_DOWNLOAD, OBSOLETE, COMMENT, MAIN, FAVORITE, POPULARITY, RECENT, FEEDBACK, PURCHASABLE) > array

companyComments
optional

< Comment > array

contentType
optional

string

createdDate
optional

string (date-time)

current
optional

boolean

description
optional

string

documentUrl
optional

string

facility
optional

< string > array

favorite
optional

boolean

fileName
optional

string

internalControl
optional

< string > array

keywords
optional

< string > array

linkCount
optional

integer (int32)

linkIds
optional

< string > array

linkIndex
optional

integer (int32)

main
optional

boolean

modifiedDate
optional

string (date-time)

name
optional

string

number
optional

string

obsolete
optional

boolean

popularityRank
optional

integer (int32)

recentRank
optional

integer (int32)

series
optional

string

title
optional

string

type
optional

enum (RENBLAD, RENNYTT)

version
optional

Version

versionlessId
optional

string

DocProperty

Type : enum (VERSIONLESS_ID, VERSION_ID, INTERNAL_ID, NAME, NUMBER, TITLE, DESCRIPTION, VERSION_LABEL, VERSION_COMMENT, VERSION_DATE, VERSION_DOCUMENT_URL, CURRENT, MAIN, KEYWORDS, PERMISSIONS, FILENAME, CONTENT_TYPE, LINK_INDEX, LINK_COUNT, LINK_IDS, DOCUMENT_URL, EDIT_URL, CREATED_DATE, MODIFIED_DATE, COMPANY_COMMENTS, RECENT_RANK, POPULARITY_RANK, CONTENT, FAVORITE, OBSOLETE, SERIES, ANLEGG, AKTIVITET1, AKTIVITET2, INTERNKONTROLL, SCORE, HIGHLIGHT_TEXT)

RenbladSeries

Name Schema

description
optional

string

firstNumber
optional

integer (int32)

lastNumber
optional

integer (int32)

title
optional

string

SearchData

Name Schema

facetGroups
optional

< SearchFacetGroup > array

matches
optional

< SearchMatch > array

numMatches
optional

integer (int32)

startMatch
optional

integer (int32)

SearchFacet

Name Schema

count
optional

integer (int32)

displayName
optional

string

longDisplayName
optional

string

name
optional

string

SearchFacetGroup

Name Schema

displayName
optional

string

facets
optional

< SearchFacet > array

name
optional

string

SearchMatch

Name Schema

activity1
optional

< string > array

activity2
optional

< string > array

capabilities
optional

< enum (HISTORY, HISTORY_DOWNLOAD, OBSOLETE, COMMENT, MAIN, FAVORITE, POPULARITY, RECENT, FEEDBACK, PURCHASABLE) > array

companyComments
optional

< Comment > array

contentType
optional

string

createdDate
optional

string (date-time)

current
optional

boolean

description
optional

string

documentUrl
optional

string

facility
optional

< string > array

favorite
optional

boolean

fileName
optional

string

highlightText
optional

string

internalControl
optional

< string > array

keywords
optional

< string > array

linkCount
optional

integer (int32)

linkIds
optional

< string > array

linkIndex
optional

integer (int32)

main
optional

boolean

modifiedDate
optional

string (date-time)

name
optional

string

number
optional

string

obsolete
optional

boolean

popularityRank
optional

integer (int32)

recentRank
optional

integer (int32)

score
optional

number (double)

series
optional

string

title
optional

string

type
optional

enum (RENBLAD, RENNYTT)

version
optional

Version

versionlessId
optional

string

SuggestData

Name Schema

collations
optional

< Collation > array

suggestions
optional

< string, < Suggestion > array > map

Suggestion

Name Schema

text
optional

string

Version

Name Schema

comment
optional

string

date
optional

string (date-time)

documentUrl
optional

string

id
optional

string

label
optional

string

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

rensystemer

The default (and minimum) scope.

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

rensystemer

The default (and minimum) scope.