tkausch/myuplinkswift

An API client using the MyUplink RESTful API to access NIBE-S heat pump data.

myuplinkswift's Issues

Add OAuth 2.0 Client Credentials Grant for MyUplinnkClient

Implement the OAuth 2.0 client credential grant authentication as defined in rfc674. The returned token has to be stored for the client and propagated for each API call in the "Authorisation: Bearer xxxxx" header.

Use the following endpoint definitions:

Swagger: https://api.myuplink.com/swagger/index.html
Group: Identity
Endpoints: POST /oauth/token
BaseUrl: https://api.myuplink.com
Method: POST

Request Header:
Content-Type: application/x-www-form-urlencoded

Request Body:
grant_type: "client_credentials"
scope: "READSYSTEM"
client_id: "client_id_from_myuplink"
client_secret: "client_secret_from_myuplink"

Note: when you want to access writing calls. "WRITESYSTEM" has to be used as a scope.

Response Body:

{"access_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IkRERDcxNjI3QkI2MDQ3OTREQUJGRUFBQ0I2NDY5RUE3MEVFNzcwQkVSUzI1NiIsInR5cCI6ImF0K2p3dCIsIng1dCI6IjNkY1dKN3RnUjVUYXYtcXN0a2FlcHc3bmNMNCJ9.eyJuYmYiOjE2MjA5MTQ2MDcsImV4cCI6MTYyMDkxODIwNywiaXNzIjoiaHR0cHM6Ly9hcGkubXl1cGxpbmsuY29tIiwiYXVkIjoiQVBJLXYyIiwiY2xpZW50X2lkIjoiNTc5OGY1MzktYjI5Ny00NDhkLTg5MmEtZmE2YWNkMmFiZjYwIiwic3ViIjoiYWMyYjJjZTYtNDZhYy00MjhlLWFiYTAtZTczM2UzMzAxMmRjIiwianRpIjoiQUE2QzZFNDkwNTM1N0YwNjRGOEE3MEJGMTcwMkNGNTQiLCJpYXQiOjE2MjA5MTQ2MDcsInNjb3BlIjpbIlJFQURTWVNURU0iXX0.DOSFJZdUmUZjiGiQ_NTb0Qz5q7fMmTtHbM0z-v4OUA-HP_-mnJuqWyPqQYSBwjfo-UmlxN9xSXt698MpF7chHfrx-zTziP9QL5Hx8ZOPk6S6U7NT5KMtPvKnZAgJDo0aghhsyiLcrR3DkW2FgsOJRWL6mGTLAdYbyu1IOfHIWtCzcQFBtXYnpomd4LQIo9BwwXHRQ3Ye3fRHYH4BKwM5UzmCUtD2nEtF_5Q3gWIk5bwhZtKAAmDMea8JK3JhAyILJqjPR_4gqWDLgs-E29Jv7PpUM-Tl_3c8HvAhhdyTSCNRZIjW1R0ifwOQVm9rjgnMfDfsDxUNCN4cjxoED-ei9g","expires_in":3600,"token_type":"Bearer","scope":"READSYSTEM"}

HTTP Status

Handle HTTP status codes according to the following table.

Code	Description	Links
200	Success
401	Unauthorized
403	Forbidden

When errors occur an error object is returned that contains all information coming from the server.

{
"error": "invalid_request",
"error_description": "check authorization server configuration",
"code": "invalid_request",
"description": "check authorization server configuration",
"timestamp": "2021-05-13T14:16:55.8644845+00:00"
}

Acceptance Criteria

1. Send client_id and client_secret in body.
2. Store returned token
3. HTTP status codes handled

Error handling support for MyUplinkClient

The myUplink API uses HTTP response codes, as defined in the HTTP specification, to indicate the success or failure of a request. In general, response codes in the 2xx range indicate success, 4xx range indicate an error that resulted from the provided information (e.g. lack of access to resource, missing required parameter) and response codes in the 5xx range indicate an error with the myUplink servers.

All non-successful response messages contains an error message object to help troubleshoot the issue on the client side. For OAuth authorization and token requests this response message follows the convention specified in the OAuth 2 specification. Other requests responds with a JSON object with the following parameters.

Name	Description	Type
httpStatusCode	The HTTP status code returned	integer
errorCode	An error status code	ErrorCodes
timestamp	A timestamp indicating when the error occurred	string
details	List of descriptive text messages in English detailing the error	list of strings
data	Additional data to help with handling of the error	dictionary of string [key] and string [value]

Acceptance Criteria

• All Myuplink requests return error object with the above information
• The effective HTTP is encapsulated in the error.
• Error handler is implemented as strategy and can be replaced.

Language support fo MyUplinkClient

User facing strings provided by the API can be automatically translated to any of the languages supported by myUplink. This is achieved by specifying the Accept-Language HTTP header as specified in the RFC 2616 specification. The following languages are supported by the API:

Language	Language code (ISO-639)
German	de
English	en
Swedish	sv

Acceptance Criteria

• Language Attribute on each request

How can I contact you?

Hi I am interested to make a myUplink plug-in for Domoticz.
It need to be in python3.

Can I contact you for help?
I am stuck to the Bearer token.

I have develop a NibeUplink plug-in for Domoticz and it works.

Thanks

Add Continous Integration and Continous Delivery

Integrate fully automated testing and CI based on cloud infrastructure or dedicated hardware.

Acceptance Criteria:

1. Enforce successful test builds
2. Enforce test coverage
3. Provide simple releasing

Basic RESTful Client

Implement a Restful API client in Swift using Generics, Codable. Provide a closure based interface.

Acceptance Criteria:

1. Abstract HttpRestClient and MyUplinkClient
2. Generic error handling
3. JSON parsing and validation
4. Async calls
5. Handler (Closure/Block) paradigm based interface
6. API Versioning

Trigger for "Extra Hot Water" not accepted from myUplink

Getting informations from myUplink are working fine. Now I want to trigger "Extra Hot Water". In the myUplink swagger page this works perfectly with this curl statement:
curl -X 'PATCH' 'https://api.myuplink.com/v2/devices/hp24-r-20240327-04-d1-6e-d1-7f-0f/zones/40008'
-H 'accept: text/plain'
-H 'Authorization: Bearer xxx
-H 'Content-Type: application/json-patch+json'
-d '{"mode": "on"}'

I try this with your Beta NodeRed Plugin with this msg as input:
msg.deviceId = "hp24-r-20240327-04-d1-6e-d1-7f-0f";
msg.zoneId = "40008";
msg.payload = { "mode": "on"};

The answer from myUplink is:
Request content from client not accepted by server.

I use the "PATCH /v2/devices/{deviceId}/zones/{zoneId}" Output.
The write privilege is set.

Do you have an idea?

Regards
Armin

Make available as CocoaPod

The framework should be made available as CocoaPod

UP-1 Implement System ME

Implement ME function using the following API specification:

https://api.myuplink.com/swagger/index.html

group: System
endpoint: /v2/systems/me
method: GET
baseUrl: https://api.myuplink.com/

HTTP Status:

Code	Description
204	If API is alive.
401	Unauthorized
403	Forbidden

Acceptance Criteria

• Error cases handled
• Success case handled
• Unit tested using postman mock service

Mock MyUplink Backend

Simulate a MyUplink backend with Postman’s mock service. This mock can be used for development instead of a real NIBE-S system connected to My-UpLink.

Acceptance Citeria:

1. Mock must be simple
2. Mock should run in Internet
3. Mock changes should
4. Optional: Mock can be reused for unit testing client framework

Paging Support for MyUplinkClient Requests

Functions that return multiple items are paginated. In the case of pagination the function reference documentation specifies which default values are used and how to access further pages.

The following has a couple of optional parameters which are not (type, active, page and itemsPerPage)

/v2/systems/435/notifications GET /v2/systems/435/notifications?page=1&itemsPerPage=2

Implement Ping RESTful call

Implement Ping function using the following API specification:

https://api.myuplink.com/swagger/index.html

group: Pint
endpoint: oauth/token
method: GET
baseUrl: https://api.myuplink.com/

HTTP Status:

Code	Description
204	If API is alive.
401	Unauthorized
403	Forbidden

Acceptance Criteria

1. Error cases handled
2. Success case handled
3. Unit tested using mocked services

Make available for Swift Package Manager

The framework should be made available for Swift Package Manager so it can be easily integrated into iOS and Mac Apps

Acceptance Criteria

• Can be added to iOS/MacOS App with Package.swift file
• Simple mechanism to publish new versions of MyUpLink package