iws_http 1.0.0

Library to facilitate http requests with error handling for Rest API requests.

IwsHttp

Library to facilitate HTTP requests with REST APIs in Dart/Flutter. Provides JWT authentication, error handling, file upload, and convenient helpers for building API clients.

Features

• Authentication with JWT and/or API Key
• HTTP error handling with custom exceptions
• File upload (multipart/form-data)
• Support for GET, POST, PUT, PATCH, DELETE
• Timeout and secure connection options
• Path generation helper for RESTful endpoints

Getting started

Initialize the library (singleton):

IwsHttp.setup(
  authority: 'mydomain.com',
  apiKey: 'my_secret_api_key',
  basePath: 'api/',
  secureConnection: true,
  bearerToken: 'my_secret_token',
  timeout: 10, // seconds
);

Or create a new instance:

final client = IwsHttp.newInstance(
  authority: 'mydomain.com',
  apiKey: 'my_secret_api_key',
  basePath: 'api/',
  secureConnection: true,
  bearerToken: 'my_secret_token',
  timeout: 10,
);

Usage

POST request

final response = await IwsHttp().post(
  path: 'login',
  body: {'email': '[e-mail]', 'password': '1234'},
  auth: false, // Set to false if endpoint does not require JWT
);

GET request

final data = await IwsHttp().get(
  path: 'users',
  queryParameters: {'page': '1'},
);

PUT request

await IwsHttp().put(
  path: 'users/1',
  body: {'name': 'New Name'},
);

PATCH request

await IwsHttp().patch(
  path: 'users/1',
  body: {'email': '[e-mail]'},
);

DELETE request

await IwsHttp().delete(
  path: 'users/1',
);

File upload

import 'package:iws_http/file_dto.dart';

final file = FileDto(path: '/path/to/file.jpg');
final result = await IwsHttp().upload(
  path: 'upload',
  file: file,
  fields: {'description': 'Profile picture'},
);

Generate RESTful endpoint paths

final path = IwsHttp().generatePath(
  path: 'user/{userId}/payment/{paymentId}',
  pathParam: {'userId': 123, 'paymentId': 456},
);
// Result: 'user/123/payment/456'

API Reference

Methods

IwsHttp.setup(...)

Initializes the singleton instance. Call this once at app startup.

IwsHttp.newInstance(...)

Creates a new, independent instance. Useful for multiple API clients.

IwsHttp()

Returns the singleton instance (after setup).

post({required String path, body, ...})

Sends a POST request. body is encoded as JSON. Returns decoded response.

get({required String path, ...})

Sends a GET request. Returns decoded response.

put({required String path, body, ...})

Sends a PUT request. body is encoded as JSON.

patch({required String path, body, ...})

Sends a PATCH request. body is encoded as JSON.

delete({required String path, ...})

Sends a DELETE request. Optionally accepts a body.

upload({required String path, required FileDto file, ...})

Uploads a file using multipart/form-data. Accepts file path or bytes.

generatePath({required String path, Map<String, dynamic>? pathParam, String? id})

Generates a RESTful endpoint path by replacing {param} with values from pathParam.

Error Handling

All methods throw custom exceptions for HTTP errors:

• ApiException (base)
• BadRequestException (400)
• UnauthorisedException (401/403)
• DataNotFoundException (404)
• FormRequestException (422, with input errors)
• FetchDataException (other errors)

Catch these exceptions to handle errors in your app.