danirod / cartero

Make HTTP requests and test APIs

Cartero

Make HTTP requests and test APIs

Cartero is a graphical HTTP client that can be used as a developer tool to test web APIs and perform all kind of HTTP requests to web servers. It is compatible with any REST, SOAP or XML-RPC API and it supports multiple request methods as well as attaching body payloads to compatible requests.

Features:

• Loads and saves to plain Git-friendly TOML files, so that you can own your data.
• Customization and modification of the request headers and body payloads.
• Variable binding for API keys and other secret information.

Motivation

This project exists because there aren't many native graphical HTTP testing applications / graphical alternatives to cURL that are fully free software, and I think the world has had enough of Electron / non-native applications that are anonymously accesible until one day you are forced to create an account and log in to use just to make some investor happy with their numbers or to chug some unwanted artificial intelligence at users.

Download

You can also download a version for Windows or macOS.

Warning

The Windows and macOS versions are currently not notarized or signed. On first run on Windows, you'll need to confirm the SmartScreen warning. On first run on macOS, you'll need to right click the app and use the Open menu. If you don't trust these binary distributions, you can always build from sources.

	Platform	Latest version
	Windows, x86_64	v0.1.1 (installer)
	macOS, Apple Sillicon	v0.1.1 (.dmg)
	macOS, Intel	v0.1.1 (.dmg)

Building

Flatpak

Install the runtime:

flatpak install --user org.gnome.Sdk//46 org.freedesktop.Sdk.Extension.rust-stable//23.08

Install the Flatpak, possibly passing the --user parameter.

flatpak-builder --user --install flatpak_app build-aux/es.danirod.Cartero.json

You will find Cartero in your application launcher, or you can launch it with flatpak run es.danirod.Cartero.

Meson

Use this to build the application outside of a Flatpak image. Note that this method should only be used by power users, to package the application on build scripts for rolling-release distributions, or for development purposes.

Currently, to build the application you'll have to make sure that the required libraries are installed on your system.

• glib >= 2.72
• gtk >= 4.14
• gtksourceview >= 5.4
• libadwaita >= 1.5

Make sure that you have Meson in your system. For instance,

sudo apt install meson
sudo dnf install meson
sudo pacman -S meson

Then use the following commands to build and install the application

meson setup build
ninja -C build
ninja -C build install

To avoid installing system-wide the application, you can use a prefix:

meson setup build --prefix=/usr
ninja -C build
ninja -C build install

If you plan on contributing to the project, use the development profile.

meson setup build -Dprofile=development

It will also configure a Git hook so that the source code is checked prior to authoring a Git commit. The hook runs cargo fmt to assert that the code is formatted. Read hooks/pre-commit.hook to inspect what the script does.

Cargo (Rust)

This may be the preferred approach if you use rust-analyzer and tools like that, because Meson uses a separate target directory, and you might prefer to use the standard target/ directory.

You can use cargo build and cargo run to build and run the project executable, but you will still need to use Meson to build the data files (GSettings schema files, Gio resource files, gettext translations...).

You should use build-aux/cargo-build.sh. It wraps cargo build, but also compiles the data files and copies them in target/share, so that during application startup those files can be picked.

Nix/NixOS

Use this approach to install, build or try cartero on a nixos system. Instructions assume you're using a flakes nixos system, but you could install it in a regular nixos system aswell by importing the derivation and adding the appropiate src attribute on it, note that this may require some manual intervation though.

First of all, add cartero to your flake inputs so you can import the package.

{
  inputs = {
    cartero.url = "github:danirod/cartero";
  };
}

Warning

This examples assume you're passing inputs in the specialArgs so you can utilize it in others modules if you're splitting your config in multiple files.

Then in your home.packages (when using home manager) or environment.systemPackages (global nix packages), add the derivation.

environment.systemPackages = [
  inputs.cartero.packages.x86_64-linux.default
];

Tip

You can try changing the architecture, not tested in every arch atm though.

Another way is by making a nixpkgs overlay to add cartero and then install it easily.

nixpkgs.overlays = [
  (_: final: let
    inherit (inputs) cartero;
    inherit (final) system;
  in {
    cartero = cartero.packages.${system}.default
  })
];

And then in the packages list of your choice.

home.packages = with pkgs; [
  cartero
];

Note

You may need to reboot the system or relogin to be able to see cartero on your launcher

Contributing

🐛 This project is currently a larva trying to grow. Do you want to get in? Take a seat!

This project is highly appreciative of contributions. If you know about Rust, GTK or the GNOME technologies and want to help during the development, you can contribute if you wish. Fork the project and commit your code.

Some checklist rules before submitting a pull request:

• Use a feature branch, do not make your changes in the trunk branch directly.

• Rebase your code and make sure that you are working on top of the most recent version of the trunk branch, in case something has changed while you were working on your code.

• Update the locales if you changed strings. The ninja target that you are looking for is called cartero-update-po (such as ninja -C build cartero-update-po). Don't worry, you don't have to translate the strings by yourself, but make sure that the new templates are added to the .po and .pot files.

• Use the pre-commit hook. The pre-commit hook will validate that your code is formatted. It should be automatically configured if you run Meson in development mode (-Dprofile=development), but you can install it on your own or run hooks/pre-commit.hook.

The project is starting small, so if you want to do something big, it is best to first start a discussion thread with your proposal in order to see how to make it fit inside the application.

While this application is not official and at the moment is not affiliated with GNOME, you are expected to follow the GNOME Code of Conduct when interacting with this repository.

Licenses

Cartero is published under the terms of the GNU General Public License v3.0 or later.

Copyright 2024 the Cartero authors

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

The Cartero icon is published under the a Creative Commons Attribution-ShareAlike 4.0 International license.

Credits and acknowledgments

Cartero is maintained by Dani Rodríguez.

Big shoutout to the contributors who have sent patches or translations!

Also, Christian suggested Cartero as the name for the application and I liked it enough to call it like so, therefore shoutout to Christian as well!

Finally, shoutout to many of the GTK and GNOME Circle applications out there whose source code I've read in order to know how to use some of the GTK features that you cannot learn just by reading the official docs.

Blog

Dani's dev blog (in Spanish) of Cartero.

cartero's Issues

Authorization tab

• Create a new tab page in the request notebook for the Authorization information.
• Design a class system similar to the one used for bodies, where different panels can co-exist and be chosen.
• Implement some authorization schemes:
  • Basic authorization as defined in RFC 7617
  • Digest authorization as defined in RFC 7616
  • Bearer authorization as defined in RFC 6750
• Make sure that if an authorization scheme is set, the Authorization header is automatically appended to HTTP requests.

I know what OAuth is an authorization scheme that would be highly requested, but the complexity at the moment makes it outside of the scope of this issue.

Create a Rust feature to disable client side decorations

They currently cause issues on Windows and macOS.

• On Windows, they cause weird shadows to appear, and the alternative to shadows is even worse (see #19).
• Also on Windows, they are not fully compatible with features like window snapping
• On macOS, window controls are not native and are in the opposite side of the Window

A way to disable CSD during compile-time should be added to Cartero. I believe that it should be implemented as a feature, to make it easier to test it even on GNU/Linux, or even to facilitate the integration with desktop environments that do not follow the GNOME HIG, such as KDE.

• If CSD is enabled, CarteroWindow will extend Adw.ApplicationWindow, and the Blueprint shall reflect it. This is the current behaviour.
• If CSD is disabled, CarteroWindow will extend Gtk.ApplicationWindow instead, and should use a different Blueprint that adapts to the Gtk.ApplicationWindow limitations.

Also, on Windows disabling the CSDs shall set the GTK_CSD env-var to "0", because it seems that on Windows, Gtk.ApplicationWindow will try to be non-native unless the environment variable is set.

Open last session

Add to the settings object the list of opened files, keep it synchronized and open the last state on application startup.

Persist duplicate KeyValue items

Currently, storing a key-value table (such as headers or variables) uses a HashMap<String, String> data structure, which means that for a standard header table, everything works fine:

x	Header	Value
x	Accept	application/json
	Content-Type	application/json

Stored as

[headers]
Accept = "application/json"
Content-Type = { active = false, value = "application/json" }

However, since the user interface allows the user to paste duplicate keys, persisting after adding duplicate values may trigger unexpected consecuences. HashMaps cannot have duplicate keys, so only one of the values for each duplicate key will be persisted, usually the one that comes after.

x	Header	Value
x	Accept	application/json
	Content-Type	application/json
x	Accept	application/ld+json

Stored as

[headers]
Accept = "application/ld+json"
Content-Type = { active = false, value = "application/json" }

What if this is just temporary and the user is actually using the checkboxes to toggle one or another? The saved file should reflect that, while being retrocompatible.

So just like it was done to accept both strings and inline tables as values for a key-value entry, a third type should be added that is actually an array of either strings or inline tables, which means that the following could be totally acceptable:

x	Header	Value
	Accept	application/json
	Content-Type	application/json
x	Accept	application/ld+json

Stored as

[headers]
Accept = [
  { value = "application/json", active = false },
  "application/ld+json"
]
Content-Type = { active = false, value = "application/json" }

Note that the order in which keys are persisted is still not relevant, but since an item overrides any item with the same key that is above in the table, it is important for entries with the same name to be persisted in the same order as they appear in the user interface.

Known issue: application still quits if you cancel during save

Say that you try to exit Cartero with a modified file. You press Save, but you cancel instead. Currently, Cartero will exit. The expected behaviour is that the close process is aborted and therefore you have to quit Cartero again.

Multiple request encodings

Currently only raw payloads are supported, but the following encodings should be supported:

• application/x-www-form-urlencoded (the standard for forms, will encode key-value parameters).
• multipart/form-data (mostly useful for attaching files, so it is also a dependency)
• RAW (current mode, although maybe having a dropdown to pick the content type and to colorize the input field could be good).

Export as cURL command

Provide a way to export a request as a cURL command that can be pasted in a terminal.

Default language not recognized on Windows 11 PRO (23H2)

I'm experiencing an issue with the Cartero application on Windows 11 PRO (23H2) where the default language is not being recognized. Specifically, the application is not detecting Spanish as the default language, which is set as the system language on my machine.

Steps to reproduce:

• Install Cartero on Windows 11 PRO (23H2) with Spanish set as the system language.
• Launch Cartero.
• Observe that the application does not recognize Spanish as the default language.

Expected behavior:

The application should recognize Spanish as the default language and adjust its language settings accordingly.

System information:

Operating System: Windows 11 PRO (23H2)
Language: Spanish (set as system language)

Let me know if you'd like me to add or modify anything!

Export as code (axios, fetch, Go net/http...)

Tab to explore and update query params

Most programs like this have a tab for this, and when using Cartero I find that not having a feature like this makes my work more difficult.

There should be an additional tab called Parameters, with a KeyValuePane inside.

Modifying the URL in the request_url field should update the parameters presented in the field. Modifying the contents of the KeyValuePane for the parameters should cause the parameters to be grouped again into a querystring, and the request_url should have its current URL changed as well.

Disabling a param from the pane should remove it from the URL as well.

I believe this is going to be tricky because changing the contents of the request_url after touching the pane may cause a "request_url has changed" event to fire back, entering an infinite loop. I suspect I'm going to need to add a mutex that prevents both event listeners from trying to update one each other.

"About Window" Does not change language

Issue: "About" Window Does Not Change Language

Description

I noticed that the "About window" of the application does not change its language. While the rest of the application is correctly displayed in this case, Spanish , the "About window" remains in English.

Expected Behavior

The "About window" should display text in the os language, in this case, Spanish, along with the rest of the application.

Actual Behavior:

The "About window" remains in English regardless of the language setting.

Environment

• Application Version: 0.1.1
• OS: Windows 11

Label: color status code

When you make requests, the response's status code has a neutral color. It would be nice if colors changed depending on status

Collections

Preview generated headers

Since some panels generate their own headers (the body generates a Content-Type, the authorization may generate an Authorization...), previewing some read-only headers in the Headers tab may be useful.

These headers are just cosmetic and presented in the Headers tab. So the KeyValueItem and friends should receive a new property called "cosmetic", which makes them read only and non-serializable, since the header should not end in the files.

• Add a cosmetic property to the KeyValue thingies and render them properly.
• Assert that cosmetic headers are ignored when sending the request (because the value of the header is taken from the real values themselves).
• Assert that cosmetic headers are ignored when saving the request to a file.
• Assert that the user can still overwrite the value of a cosmetic header by adding a new header with the same name (the cosmetic header shall be strikethrough as well).

For some cosmetic headers, the value may be fully pregenerated. For instance,

• A body of type JSON may already have Content-Type: application/json
• An authorization header of type Bearer may already have Authorization: Bearer 12341234

However, this is not true for every cosmetic header, because some of them only get generated when the request is submitted. Multipart requests do this because the boundary has to be generated on demand to prevent conflicts with the payload.

Save as

User agent header value must be filled

Unless the user changes the value, the default user agent to be submitted should be something like Cartero/1.0 (+https://github.com/danirod/cartero).

This depends on having a way to set placeholder values for a header, and to allow disabling the "remove" button.

Migrate artifacts to nightly.link

Given that I am building more artifacts now (Flatpak, Windows, coming soon macOS and AppImage), maybe pushing the artifacts into a release is not very extensible.

My idea is to just deploy them as standard GitHub Actions artifacts and then use nightly.link to get a download link for the latest artifact.

Enter Key Event to Trigger Request Submission

Add functionality to submit requests when the Enter key is pressed, improving user efficiency.

I hope you consider this request. Thank you!

Support broken SSL certificates

Currently, if the web server has an invalid SSL/TLS certificate and does not validate, the request fails, and there is an HTTP error with no further explanation.

• Properly document and display the error message in that case.
• Allow to deactivate SSL validation

It doesn't recognize POST body object on Windows

I just downloaded the windows and tried to execute a common POST request that I use but didnt work, I'm not sure maybe Im indenting wrong or something like that

This is the request in postman

This is the request in Cartero:

Warn before close

When Cartero is closed, it is necessary to warn the user about any endpoint whose data has not been persisted yet since the file was opened.

Al guardar una petición se guarda junto a la versión previa

Al guardar una petición:

• Si es la primera vez se guarda los datos.
• Al realizarlo una segunda vez o más se genera un archivo adicional que conserva los datos previos.

Pasos para reproducir el problema:

1. Guardar el archivo más de una sola vez.

cartero-bug.webm

Entorno:

• Cartero: 0.1.1
• Windows 10 Home Single Language 22H2, procesador basado en x64

Add option to check if new version is available (feature)

On startup, show a local notification if a new version is available.

Loses query parameters if the request is saved after deactivating one of them

Say that you have an URL like https://example.com/?a=1&b=2&c=3.

And then you use the checkbox to "temporally" disable the queryparam a.

Except that you press [Save]. Well, it seems that the a query parameter has dissapeared from your file, which means that if you close and reopen the request, the query parameter will be gone for good.

Add a component to render JSON values

I think that the best option is to do something like what Firefox does when you open a JSON file, which is to present non-primitive types as a tree.

At the moment my main priority is JSON.

Better packaging for Windows

• Use winres to add an icon to cartero.exe
• Also use winres to pack metadata into the executable (copyright information, original filename, and so on)
• Create an installer. I may remember a little about NSIS, but InnoSetup is also open source and it is made on Pascal so it is more cool.

Syntax highlighting

Depending on the value of the content-type header for the response, I could load a specific syntax highlighter, such as JSON, TOML, YAML, HTML or XML.

Productivity / Accessibility in cartero

When enter the API in the text bar i want to access, it would be nice if after press enter, send the request.

I have tried that it does not work so much in Ubuntu with Windows.

The app looks amazing.

Thanks.

Support for meson devenv

This is going to make testing the application in development mode way easier.

Broken links in "About Cartero" section

I've noticed that the links in the "About Cartero" section are not functioning properly. When I click on them, I'm not taken to the expected webpage or resource.

Steps to reproduce:

• Open the Cartero application.
• Navigate to the "About Cartero" section.
• Click on any of the links provided.
• Observe that the link does not work as expected.

Expected behavior:

The links in the "About Cartero" section should be functional and take the user to the intended webpage or resource.

System information:

Operating System: Windows 11 PRO (23H2)

Let me know if you'd like me to add or modify anything!

Add AppStream Metainfo File

A requirement in order to pack for Flathub.

Known issue: missing icons

It is known that currently some application icons may not present properly. This issue affects any version that is not packaged via Flatpak: Windows, macOS and non-sandbox GNU/Linux.

I'm looking for workarounds and I'll probably just embed some icons into the application to make sure that they always work.

Attach binary files to requests

Allow to enable or disable backups

I've noticed that whenever I press Save, I get a backup file created. If I am already using Git, I don't see the point on having a backup. I don't want to get rid of backups because maybe someone finds them useful.

You know, add this to the settings page.

Configure redirect policy for HTTP requests

Sometimes a request will return a response in the range of HTTP 3xx. Currently Cartero serves the received response.

Add a setting option to change this behaviour. The user can pick what to do if a redirection response is received:

• Either just use the HTTP 3xx response and show its contents.
• Or follow the redirection, up to a maximum amount of redirects.

Broken window/popup transparency on Windows

Rendering info as requested

Known issue: wrong keyboard shortcuts on macOS

The macOS version doesn't use the proper keyboard shortcuts for some actions such as cut, copy, paste and select all.

This is a known issue that affects upstream dependencies, and there is not much to fix here at the moment, so I'm marking this as a Known issue if someone ever reports this as a bug in Cartero.

---

More context: currently, GTK 4 apps use <Ctrl> as the primary modifier for all keyboard shortcuts. On GNU/Linux and Windows this makes sense because the keyboard shortcuts are already Ctrl-X, Ctrl-C, Ctrl-V. However, on macOS most users will expect Cmd-X, Cmd-C and Cmd-V as the keyboard shortcuts to cut, copy and paste.

Solution 1: upstream GTK. On GTK 4.16, they will change the primary modifier to <Meta> (the Cmd key) on macOS. The merge request has been already integrated. If we just wait until GTK 4.16 is stable, once it is possible to compile a macOS version with that version, the issue will probably be automatically fixed.

Solution 2: language bindings. There is a workaround to change the keyboard shortcuts for cut, copy and paste. Many apps already use it to have better compatibility with macOS. Unfortunately, there seems to be some kind of issue at the moment with the language bindings for the UI toolkit that Cartero uses which currently prevents me from using the workaround in my application.

Updates for Windows and macOS

There is sparkle-updater. It is not on crates.io for some reason, but dependencies can be added from a Git repository (what if it dissapears, can I vendor it?)

Compile for macOS

For now I am going to focus on GNOME because it will help me get the application done, but the application should work on macOS since that will also meet the expectations of many developers that will be otherwise forced to use other worse graphical HTTP client.

Tasks and subtasks:

• Make sure that the application compiles and runs under macOS using the development code.
• Provide a script that packages the application into a Cartero.app.
  • Use otool to make sure that dependencies are packaged within the application (this is going to be the difficult task)
  • Pack an .icns icon for macOS.
  • Deploy into Cartero.app.
  • Compile nightly releases in GitHub Actions.
• Evaluate notarizing the application to mark it as safe.

Known issue: no support for streaming requests

It is known that currently some HTTP requests that use HTTP streaming may hang the user interface. An example request of this is https://httpbin.org/range/1500. Other requests may exist.

In general, support for streaming requests and server side events is currently not well tested and this will probably not change until 0.1 gets released in order to focus my limited resources into finishing the first version of the app.

Secret variables and headers

Allow to mask a value input so that the contents are not visible out of the box, which is good to encode API keys and other sensible data that you'd rather not show, for instance, if screensharing.

This requires storing data in the KeyValue data structure, since the information is also required to avoid serializing the value into a file.

More keyboard shortcuts

List of shortcuts to add for 0.1:

• <Primary>-T: open a new tab.
• <Primary>-O: open an existing file.
• <Primary>-S: save or prompt to save new file.
• <Primary>-W: close tab.
• <Primary>-Q: exit Cartero.
• <Primary>--S: save as new file.

Settings page

This is the meta-task for the settings page and the different things that have to go there.

• Add a settings dialog.
• Connect the settings via an action that opens the settings as a modal dialog.
• Bind the action to the <Primary>, keybinding.
• Add a trigger for the action to the application menu.

Things that go in the settings page:

• Overwrite application theme (follows system by default, but user should be able to change it to Light or Dark).
• Custom font for the body panes (enabled or disabled toggle, and a button to change the font)
• Redirect policy
• What to do with invalid SSL certificates
• Behaviour on application startup (open last session, empty request, welcome page)

Store request metadata: title, description...

This allows a request to show a different display name than the file name, as well as provide a description.

It may also be necessary for a proper OpenAPI import and export.

El contenido del resultado de la consulta no se adapta al tamaño

El contenido del resultado de la consulta no se siempre se adapta al tamaño del contenedor, lo que causa que el resultado desborde y aparezca un deslizador horizontal. Este comportamiento ocurre incluso cuando en las configuraciones se indica que en la apariencia del cuerpo Se adapte el contenido.

Pasos para reproducir el problema:

1. Realizar una petición HTTP a https://randomuser.me/api/?results=2&format=csv.

Entorno:

• Cartero: 0.1.1
• Windows 10 Home Single Language 22H2, procesador basado en x64