Issuu on Google+

Om api.finn.no Api.finn.no er et RESTfult hypermediadrevet API. Basisprinsippet er at det leverer innhold som linker til annet relevant innhold. APIet er i stor grad selvdokumenterende gitt at dataene som leveres i seg selv beskriver hva en klient kan gjøre og forvente å finne. Mangt er skrevet om denne type API, og her finner du noe av det:    

Roy Fielding - REST Wikipedia - REST REST in practice Wikipedia - Hypermedia

Om dette dokumentet Dette dokumentet inneholder dokumentasjon av api.finn.no. Generell dokumentasjon og beskrivelser står på norsk, mens detaljert dokumentasjon er på engelsk. Mye av informasjonen som er relevant for APIet er allerede beskrevet i detalj andre steder siden vi i all hovedsak benytter åpne standarder i APIet.

Hva du trenger Tilgang API-klienter bruker en tilgangsnøkkel for å få aksess. Nøkkelen sendes med alle requests i headeren på denne måten: GET https://hostname/resource x-finn-apikey yourKeyHere

Service-dokument Service-dokumentet er startpunktet for APIet. Her finnes en oversikt over tjenestene som finnes. https://cache.api.finn.no/iad/

Standarder og Mediatyper Disse standardene og mediatypene brukes i APIet.      

HTTP XML JSON Atom Atompub Atom expires extension


    

Opensearch GeoRSS extension MediaRSS extension vCard Dates on the Internet

I tillegg finnes FINN-spesifike utvidelser.

FINN extensions Atom extensions This section is a description of the extensions under the FINN.no XML namespace. The extensions have been designed to fit nicely in with Atom. We will follow a strict RFC-like format for the documentation. There will be a schema described inline in RELAX-NG compact format. This schema will also be available elsewhere. This specification uses XML Namespaces W3C.REC-xml-names-19990114 to uniquely identify XML element names. It uses the following namespace prefix for the indicated namespace URI: "finn" : "http://xmlns.finn.no/atom-ad-extensions/1.0"

Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this documentation are to be interpreted as described in BCP 14, RFC2119, as scoped to those conformance targets. The word Atom is referenced to be RFC-4287. The word atompub is referenced to be RFC5023. The elements will reuse a lot of existing Atom elements and definitions, any types starting with atom MUST be considered from the Atom spec.

Elements finn:location Represents the geographic location where the Ad may be found. Formally the location element is defined like this: finnLocation = element finn:location { atomCommonAttributes, (extensionElement* & (finnAddress*, finnCity?,


finnPostalCode?, finnCityDistrict?, finnCountry?)) } finnAddress = element finn:address { atomCommonAttributes, text } finnCity = element finn:city { atomCommonAttributes, text } finnPostalCode = element finn:postal-code { atomCommonAttributes, text } finnCityDistrict = element finn:city-district { atomCommonAttributes, text } finnCountry = element finn:country { atomCommonAttributes, text }

finn:contact Represents a Contact for an Ad. The atom:uri element of the contact will contain a link which can be used for sending email. The contact elements will usually appear on an atom:entry element. Formally the contact element is defined like this: finnContact = element finn:contact { atomPersonConstruct & finnPhone* }

The type attribute The type attribute is optional and SHOULD be considered have the value organization if it does not appear, or has an unknown value.


The type attribute should be considered to have the following set of values:     

organisation individual realestate:agent realestate:financial-agent realestate:developer

The set is expandable, and there WILL be a registry where clients can find information about what each type means. User Agents can always interpret unknown values as being equal to organization , for interop.

finn:phone Represents a phone number. This SHOULD be a display value only. User Agents SHOULD NOT rely on phone numbers being represented by a parsable format. Formally the phone element is defined like this: finnPhone = element finn:phone { atomCommonAttributes, attributetype { string `fax`, string `mobile`, string `home`, string `work` }, text }

finn:adata Conceptually the AData element can be thought of as a container element for Ad data. An AData element can contain Field(s). Formally the adata element is defined like this: finnAdata = element finn:adata { atomCommonAttributes, attributemodel { atomUri }, (finnField & finnPrice & extensionElement)* }


The model attribute The model attribute is an IRI to a model describing the fields. Processing model The model attribute serves two purposes:  

Target to be able to get the Model document Used as an identifier to be able to recognize previously parsed Model documents.

User Agents are expected to have previously downloaded the resource identified by the target IRI, as it is the most common use case. Fields referenced which does not exist in the model, MUST be ignored by the agent. It is NOT an error having unknown fields, and User Agents MUST handle absence of fields.

finn:field Formally the field element is defined like this: finnField = element finn:field { atomCommonAttributes, attribute name { atomNCName }, (attribute value { text } | attribute from { text } | attribute to { text } | (attribute from { text } , attribute to { text } )) | (finnValue|finnField|xhtml: div|text)* & extensionElement*) }

A field has a name and a value. A name SHOULD be referenced in the model document referenced by the adata element. Processing model


A field MAY have a value attribute, and then it will have zero children. A field MAY, if it represents some range value, have either a from attribute, a to attribute, or both. If this is the case, it will have no value attribute and zero children. A field MAY have zero or more value elements and those are considered as a List type of construct. A field MAY have other field elements as children. Those should be considered a Map type of construct. A field MAY have a xhtml:div element . This should be considered rich text. A field MAY have textual content. This should be considered simple text.

finn:price Formally the price element is defined like this: finnPrice = element finn:price { atomCommonAttributes, attribute name { atomNCName }, (attribute value { text } | attribute from { text } | attribute to { text } | (attribute from { text } , attribute to { text } )) , finnField* & extensionElement* }

A price has a name and a value. A name SHOULD be referenced in the model document referenced by the adata element. Processing model A price SHOULD have a value attribute.


A price MAY have field elements as children. Those should be considered a Map type of construct.

finn:value Formally the value element is defined like this: finnField = element finn:value { atomCommonAttributes, (text|(finnField & extensionElement*)) }

finn:category Formally the category element is defined like this: finnPrice = element finn:category { atomCommonAttributes, attribute scheme { atomNCName }, attribute term { text }, extensionElement* }

A category has a scheme and a term.

OpenSearch extensions This document is a description of FINN.no extensions to OpenSearch. This specification uses XML Namespaces W3C.REC-xml-names-19990114 to uniquely identify XML element names. It uses the following namespace prefix for the indicated namespace URI: "f" : "http://xmlns.finn.no/opensearch/1.0"

Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this documentation are to be interpreted as described in BCP 14, RFC2119, as scoped to those conformance targets. The word Atom is referenced to be RFC-4287. The word atompub is referenced to be RFC5023.


The elements will reuse existing Atom elements and definitions. Any types starting with atom MUST be considered from the Atom spec. Elements starting with the f prefix MUST be considered from the OpenSearch namespace.

Elements f:template Formally the template element is defined like this: fTemplate = element f:template { atomCommonAttributes, attribute href { text }, attribute rel { text }? }

The href attribute The href attribute defined to follow the format of URI-templates. The rel attribute The rel attribute is defined to follow the rules of section 4.2.7.2 in the Atom spec, with the additional support for CURIE

f:filter Formally the filter element is defined like this: fFilter = element f:filter { atomCommonAttributes, attribute name { atomNCName }, attribute range { xsd: boolean }?, (extensionElement & osQuery)* }

f:Query restrictions


The role attribute SHOULD be set to subset . The attribute f:filter SHOULD be present with the filter value. The attribute f:from SHOULD be present if parent element f:filter has the range attribute set to true . The attribute f:to MAY be present if parent element f:filter has the range attribute set to true . Processing model The presence of f:filter in an Atom document or Opensearch Description document means that User Agents SHOULD consider the f:filter as a source for adding query parameter to the context URI. For feeds there SHOULD be an atomLink with the rel="self" , which SHOULD be used as the context URI. A filter MAY be applied multiple times. The filter selection algorithm is out-of-scope for this specification. Query construction Normal query name: 

the value of the name attribute

If the f:filter has the range attribute set to true , the name of the query parameter should be constructed using the following rule:   

the value of the name attribute add _from to indicate the lower value of the range. add _to to indicate the higher value of the range.

f:sort Formally the sort element is defined like this: fSort = element f:sort { atomCommonAttributes, attribute name { atomNCName }, (extensionElement & osQuery)* }

Processing model


The presence of f:sort in an Atom document or Opensearch Description document means that User Agents SHOULD look for a f:template element with the /relations/sort relation. The URI template MUST have a template variable called f:sort . This template SHOULD then be filled out with the selected filter values. Filling out the template works by finding the interesting f:Query elements with the values that are interesting, and applying the f:sort attribute to the found template. The selection algorithm is out-of-scope for this specification.

OpenSearch Suggestions Extensions This document is a description of FINN.no extensions to OpenSearch Suggestions. The OpenSearch Suggestions response is extended with two ordered collections of values: * searchKey - An identifier for the type of search the Query URL leads to * imageUrl - Link to an image for the result The ContentType for the extended result is application/x-finn-suggestions+json

FINN urn This section describes the custom Uniform Resource Names used in the API. URNs and related syntax are described in RFC2141.

Custom Uniform Resource Names urn:finn:market An URN describing which market a link/collection/etc belongs to.

urn:finn:model An URN used to describe the rel linking to a ad model

urn:finn:logo:type An URN describing the type ( category ) of logo contained in a media:content .

urn:finn:ad:private An URN used as scheme on a category to describe if an ad is considered to be from a private person of not. Valid term s: * true * false


urn:finn:ad:type An URN used as scheme on a category to describe the type of advert. Attribute label gives a human readable description, attribute term is for machine identification

urn:finn:ad:status An URN used as scheme on a category to describe the status of an ad. Some (not exhaustive) legal term s: * activated

urn:finn:ad:disposed An URN used as scheme on a category to describe if an ad has been "sold" or not. The label will provide the human readable description of the disposed status, that can change from market to market. Valid term s: * true * false

urn:finn:search:notification An URN used as scheme on a category to describe which types of notifications ('email' for instance)) a user have chosen for a stored search. The label will provide the human readable description of notification. Valid term (this will soon be expanded): * email

urn:finn:category:link An URN describing the category of a link

urn:finn:attachments Attachments use media:content from the MediaRSS extension.

urn:finn:authorize An URN describing resources that take a federated authentication token and returns an authorization token for API use. The parameters and the uri template are described in the service documentation. A text/html GET-request to the resource will return a form describing the parameters. The resource will return a json-object with API token: { "access_token": "<token-string>", "token_type": "bearer", "scope": "/", "state": "echo"


}

urn:finn:deauthorize An URN describing resources for invalidating API tokens. No parameters are accepted. Authorization-header with Bearer-token on the following form required: Authorization: Bearer <token-string>


Api dokumentasjon