Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Enhance MinFraud Documentation: Add Detailed Information on Available Options #152

Merged
merged 4 commits into from
Aug 9, 2023
Merged

Enhance MinFraud Documentation: Add Detailed Information on Available Options #152

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cc53690
Add an options section to README
faktas2 Aug 3, 2023
f1d4476
Remove options, update section
faktas2 Aug 4, 2023
a5300be
Make summary smaller, extend host in API docs
faktas2 Aug 4, 2023
375650e
Minimal changes in README
faktas2 Aug 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 20 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,10 +83,26 @@ and [Report Transaction](https://dev.maxmind.com/minfraud/report-transaction/) A

### minFraud API ###

To use the minFraud API, create a new `\MaxMind\MinFraud` object. The constructor
takes your MaxMind account ID, license key, and an optional options array as
arguments. This object is immutable. You then build up the request using the
`->with*` methods as shown below. Each method call returns a new object. The
To use the MinFraud API, you'll need to create a new `MaxMind\MinFraud` object. The constructor
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why'd we lose the \? Can we keep this as minFraud API? The original phrasing seems fine.

requires your MaxMind account ID, license key, and an optional [`options`](https://maxmind.github.io/minfraud-api-php/doc/v1.23.0/classes/MaxMind-MinFraud.html#method___construct) array as arguments. The `options` array can be used to set additional parameters such as `host` and `timeout`. Remember that this object is immutable.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, having the version number in the URL is not ideal. I think that was a poor suggestion on my part. Maybe we can refer to the API documentation generally instead, e.g. "See the API documentation for the possible options."


Here's an example of creating a `MinFraud` object and calling the Sandbox endpoint:

```php
<?php
// Set any options you need, such as the host for the Sandbox environment
$options = [
'host' => 'sandbox.maxmind.com'
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we update the API docs to discuss the sandbox host too, like we do for the geolite host for the GeoIP2 APIs? That is, we could expand the comment about the host option.

];

// Create a MinFraud object with your account ID, license key, and options
$mf = new MaxMind\MinFraud(1, 'ABCD567890', $options);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This could be just new MinFraud I think - see example below.


// Now you can use the $mf object to interact with the MinFraud API
?>
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we make this more succinct? This is a big block in the summary section of the docs. I think it would be good to keep this section as clear and simple as possible.

e.g.

For instance, to call the Sandbox environment instead of the minFraud 2 web service:

$client = new MinFraud(1, 'ABCD567890', [ 'host' => 'sandbox.maxmind.com' ]);


Build up the request using the `->with*` methods as shown below. Each method call returns a new object. The
previous object is not modified.

If there is a validation error in the data passed to a `->with*` method, a
Expand Down