Best practices

Utvikling av integrasjoner

Hvem er jeg?

            $ curl 'https://tripletex.no/v2/token/session/>whoAmI'
            
            {
                "name": "Julian Ravn Thrap-Meyer",
                "email": "julian@tripletex.no",
                "role": "Techlead API 2"
            }
            
          

          $ curl 'https://tripletex.no/v2/#table-of-contents'
          
          [
              "Ressurser",
              "Tips og triks",
              "Kommende funksjonalitet"
              # Kom gjerne med spørsmål underveis!
          ]
          
          

Ressurser

          $ curl 'https://tripletex.no/v2/#resources'
          
          [
              "Swagger",
              "FAQ",
              "Workplace",
              "GitHub"
          ]
          
          

Swagger

Beta-endepunkter

FAQ

Workplace

GitHub

Tips og triks

          $ curl 'https://tripletex.no/v2/#tips-and-tricks'
          
          [
              "fields",
              "version"
          ]
          
          

Fields

          $ curl 'https://tripletex.no/v2/#fields'
          
          [
            "Velg hvilke felter man ønsker i retur",
            "Rekursivt for underobjekter",
            "Slå sammen flere kall til ett"
          ]
          
          

Eksempel

Hent ut alle prosjekter med e-postadressen til prosjektleder

          $ curl 'https://tripletex.no/v2/project'
          
          {
            "id": 987654,
            "version": 2,
            "url": "tripletex.no/v2/project/987654",
            "name": "Mitt prosjekt",
            "number": "43",
            "projectManager": {
              "id": 45678,
              "url": "tripletex.no/v2/employee/45678"
            },
            "startDate": "2013-03-01",
            "endDate": null,
            …
          }
          
          

          $ curl 'https://tripletex.no/v2/project' -G \
                    -d fields='name,projectManager(email)'
          
          {
            "name": "Mitt prosjekt",
            "projectManager": {
              "email": "julian@tripletex.no"
            }
          }
          
          

          $ curl 'https://tripletex.no/v2/project' -G \
                    -d fields='name,projectManager(*)'
          
          {
            "name": "Mitt prosjekt",
            "projectManager": {
              "id": 45678,
              "version": 12,
              "url": "tripletex.no/v2/employee/45678",
              "firstName": "Julian Ravn",
              "lastName": "Thrap-Meyer",
              "employeeNumber": "",
              "dateOfBirth": "2018-03-06",
              "email": "julian@tripletex.no",
              "phoneNumberMobile": "",
              "nationalIdentityNumber": "",
              "dnumber": "",
              "bankAccountNumber": "",
              "address": {
                "id": 1234,
                "url": "tripletex.no/v2/address/1234"
              },
              "department": {
                "id": 2345,
                "url": "tripletex.no/v2/department/2345"
              },
              "employments": [ {
                "id": 3456,
                "url": "tripletex.no/v2/employee/employment/3456"
              } ]
            }
          }
          
          

Version

Eksempel

Øke prisen (med moms) på alle produker med 10%

1. Hent alle produkter: GET /product
2. For hvert produkt, øk pris med 10%: PUT /product/{id}

          $ curl 'https://tripletex.no/v2/product'
          
          {
            "id": 123,
            "version": 10,
            "name": "Fantastisk produkt",
            "priceIncludingVatCurrency": 1000.0,
            …
          }
          
          

          $ curl -X PUT 'https://tripletex.no/v2/product/123' \
              --data '{ "priceIncludingVatCurrency": 1100.0 }'
          
          # HTTP/1.1 200 OK
          {
            "id": 123,
            "version": 12, # oi, hvor ble det av 11?
            "name": "Fantastisk produkt",
            "priceIncludingVatCurrency": 1100.0,
            …
          }
          
          

          $ curl -X PUT 'https://tripletex.no/v2/product/123' \
              --data '{ "priceIncludingVatCurrency": 1100.0,
                        "version": 10 }'
          
          # HTTP/1.1 409 Conflict
          {
            "status" : 409,
            "code" : 8000,
            "message" : "RevisionException",
            "requestId" : "862839bc-6ac6-4e60-b871-485c887f02fb"
          }
          
          

Version

          $ curl 'https://tripletex.no/v2/#version'
          
          [
            "Unngår konflikter",
            "Returnerer HTTP 409 i stedet for å overskrive"
          ]
          
          

Kommende funksjonalitet

          $ curl 'https://tripletex.no/v2/#upcoming-features'
          
          [
              "checksum",
              "webhooks"
          ]
          
          

Checksum

          $ curl 'https://tripletex.no/v2/#checksum'
          
          [
              "Har datasettet endret seg?"
          ]
          
          

Eksempel

Synkroniser alle posteringer inn i et annet system

          $ curl 'https://tripletex.no/v2/ledger/posting' -G \
              -d dateFrom="2018-03-01" -d dateTo="2018-04-01"
          # ............
          {
              mye data,
              "checksum": "abc123"
          }
          
          

Litt senere …

          $ curl 'https://tripletex.no/v2/ledger/posting' -G \
              -d dateFrom="2018-03-01" -d dateTo="2018-04-01" \
              -d checksum="abc123"
            
          # HTTP/1.1 304 Not Modified
          {
              # veldig kjapt, uten data
          }
          
          

Igjen litt senere …

          $ curl 'https://tripletex.no/v2/ledger/posting' -G \
              -d dateFrom="2018-03-01" -d dateTo="2018-04-01" \
              -d checksum="abc123"
          
          # ............
          {
              mye data,
              "checksum": "def456"
          }
          
          

Hvorfor?

• Sparer prosesseringskraft for oss
• Mulig å spørre om endringer oftere
• Bedre for alle sammen :-)

Når?

Checksum er mulig å teste i dag

Ta kontakt!

Webhooks

          $ curl 'https://tripletex.no/v2/#webhooks'
          
          [
              "Checksum 2.0",
              "Få beskjed når ting skjer – helt automatisk!"
          ]
          
          

Eksempel

Synkroniser alle posteringer inn i et annet system (igjen)

Sett opp webhook-abonnement

          $ curl 'https://tripletex.no/v2/event/subscription' \
              -X POST --data '{
                "eventKey": "Posting.CREATE",
                "callback": "https://myapp.example/webhook"
              }'
          
          

Start webserver

          $ ./start-webhook-server
          # Listening to https://myapp.example/webhook .........
          # Data received!
          {
            "id": 253161,
            "number": "412",
            "description": "Eksempelpostering"
          }
          
          

Hva kan jeg abonnere på?

• CREATE
• UPDATE
• DELETE
• Andre ting? Kom gjerne med forslag!

Når?

Om ikke altfor lenge!

Oppsummering

• Swagger, GitHub, FAQ, Workplace
• Fields, version
• Checksum, webhooks

Presentasjonen ligger på GitHub!

Takk for meg! :-)

https://jrtm.github.io/tripletex-talks/best-practices.html